{"id":28918319,"url":"https://github.com/akougkas/zulipchat-mcp","last_synced_at":"2026-02-22T19:06:59.299Z","repository":{"id":300235073,"uuid":"1004573764","full_name":"akougkas/zulipchat-mcp","owner":"akougkas","description":"ZulipChat MCP Server - A Model Context Protocol server that bridges AI agents with Zulip Chat. Built with FastMCP for lightning-fast performance, featuring comprehensive chat management and intelligent summarization. Transform your Zulip workspace into an AI-powered collaboration hub!","archived":false,"fork":false,"pushed_at":"2026-01-22T10:38:02.000Z","size":2575,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T01:01:42.255Z","etag":null,"topics":["ai-agent","ai-integration","automation","fastmcp","mcp","messaging","model-context-protocol","zulip"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akougkas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-06-18T21:00:49.000Z","updated_at":"2026-01-22T10:38:05.000Z","dependencies_parsed_at":"2025-06-20T15:37:28.029Z","dependency_job_id":"f00cc6de-57b3-46ba-bf57-0691686fe3e2","html_url":"https://github.com/akougkas/zulipchat-mcp","commit_stats":null,"previous_names":["akougkas/zulipchat-mcp"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/akougkas/zulipchat-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fzulipchat-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fzulipchat-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fzulipchat-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fzulipchat-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akougkas","download_url":"https://codeload.github.com/akougkas/zulipchat-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akougkas%2Fzulipchat-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29723595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-22T15:10:41.462Z","status":"ssl_error","status_checked_at":"2026-02-22T15:10:04.636Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-integration","automation","fastmcp","mcp","messaging","model-context-protocol","zulip"],"created_at":"2025-06-22T02:02:39.187Z","updated_at":"2026-02-22T19:06:59.268Z","avatar_url":"https://github.com/akougkas.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ZulipChat MCP Server\n\n\u003cdiv align=\"center\"\u003e\n\n  \u003ch3\u003eConnect your AI assistant to Zulip with 8 powerful tool categories via MCP\u003c/h3\u003e\n\n  [![PyPI](https://img.shields.io/pypi/v/zulipchat-mcp)](https://pypi.org/project/zulipchat-mcp/)\n  [![Downloads](https://img.shields.io/pypi/dm/zulipchat-mcp)](https://pypi.org/project/zulipchat-mcp/)\n  [![GitHub stars](https://img.shields.io/github/stars/akougkas/zulipchat-mcp)](https://github.com/akougkas/zulipchat-mcp/stargazers)\n  [![Last commit](https://img.shields.io/github/last-commit/akougkas/zulipchat-mcp)](https://github.com/akougkas/zulipchat-mcp/commits/main)\n  [![Python](https://img.shields.io/pypi/pyversions/zulipchat-mcp)](https://pypi.org/project/zulipchat-mcp/)\n  [![License](https://img.shields.io/github/license/akougkas/zulipchat-mcp)](LICENSE)\n  [![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)\n\n  [🚀 Quick Start](#-quick-start) • [📦 Installation](#-installation) • [📚 Features](#-what-can-you-do) • [🛠️ Tools](#-available-tools) • [💡 Examples](#-real-world-examples) • [📖 Releases](#-releases) • [🤝 Contributing](CONTRIBUTING.md)\n\u003c/div\u003e\n\n---\n\n## Quick Start\n\nGet your AI assistant connected to Zulip in **30 seconds**:\n\n```bash\n# Run setup wizard (recommended)\nuvx --from zulipchat-mcp zulipchat-mcp-setup\n```\n\nOr manually with a zuliprc file:\n```bash\nuvx zulipchat-mcp --zulip-config-file ~/.zuliprc\n```\n\n## What Can You Do?\n\nYour AI assistant becomes a **Zulip superuser**, capable of:\n\n- **Intelligent Messaging** - Send, schedule, search, and manage messages with context awareness\n- **Stream Management** - Create, configure, and analyze streams with engagement metrics\n- **Real-time Monitoring** - React to events, track activity, and automate responses\n- **Advanced Analytics** - Generate insights, sentiment analysis, and participation reports\n- **File Operations** - Upload, share, and manage files with automatic distribution\n- **Workflow Automation** - Chain complex operations with conditional logic\n\n## Available Tools\n\n40+ tools across 8 categories:\n\n| Category | Count | Highlights |\n|----------|-------|------------|\n| **Messaging** | 12 | Send, edit, schedule, cross-post, reactions |\n| **Streams** | 2 | List and query stream details |\n| **Topics** | 2 | List topics, cross-stream operations |\n| **Users** | 12 | Profiles, presence, groups, muting |\n| **Search \u0026 Analytics** | 6 | Narrow filters, AI insights, summaries |\n| **Events** | 4 | Queues, long-polling, webhooks |\n| **Files** | 2 | Upload, share, manage |\n| **System** | 6+ | Identity switching, workflows, chains |\n\n\u003cdetails\u003e\n\u003csummary\u003eView all tools by category\u003c/summary\u003e\n\n### Messaging Tools\n- `message` - Send, schedule, or draft messages with smart formatting\n- `search_messages` - Token-limited results with narrow filters\n- `edit_message` - Edit content and topics with propagation modes\n- `bulk_operations` - Progress tracking for bulk actions\n- `message_history` - Audit trail with edit timestamps\n- `cross_post_message` - Attribution-aware sharing across streams\n- `add_reaction` / `remove_reaction` - Emoji support (Unicode, custom, Zulip)\n- `mark_read` / `mark_unread` - Read state management\n- `schedule_message` / `cancel_scheduled` - Delayed delivery\n\n### Stream \u0026 Topic Tools\n- `get_stream_info` - Stream details with subscriber lists\n- `list_streams` - Filter by subscription status\n- `list_topics` - Topics within a stream\n- `manage_topics` - Cross-stream transfers with propagation\n\n### User Tools\n- `manage_users` - Multi-identity support (user/bot contexts)\n- `switch_identity` - Session continuity with validation\n- `manage_user_groups` - Group lifecycle and membership\n- `get_presence` - User online status\n- `set_status` - Status emoji and text\n- `mute_user` / `unmute_user` - User muting\n\n### Search \u0026 Analytics Tools\n- `advanced_search` - Multi-faceted search with ranking\n- `analytics` - AI-powered insights with sentiment analysis\n- `get_daily_summary` - Activity summaries with engagement\n\n### Event Tools\n- `register_events` - 20+ event types with auto-cleanup\n- `get_events` - Long-polling with queue validation\n- `delete_queue` - Queue cleanup\n- `listen_events` - Webhook integration\n\n### File Tools\n- `upload_file` - Progress tracking with auto-sharing\n- `manage_files` - File lifecycle with metadata extraction\n\n### System \u0026 Workflow Tools\n- `server_info` - Server metadata with routing hints\n- `tool_help` - On-demand documentation\n- `execute_chain` - Workflow automation with branching logic\n- `register_agent` - Agent session tracking\n- `agent_message` - Bot identity messaging\n\n\u003c/details\u003e\n\n## Installation\n\nOne command to connect your AI to Zulip:\n\n```bash\nuvx zulipchat-mcp --zulip-config-file ~/.zuliprc\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSetup Wizard\u003c/b\u003e - guided configuration\u003c/summary\u003e\n\n```bash\nuvx --from zulipchat-mcp zulipchat-mcp-setup\n```\n\nThe wizard finds your zuliprc files, validates credentials, and generates MCP client config.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nclaude mcp add zulipchat -- uvx zulipchat-mcp --zulip-config-file ~/.zuliprc\n```\n\nWith dual identity (user + bot):\n```bash\nclaude mcp add zulipchat -- uvx zulipchat-mcp \\\n  --zulip-config-file ~/.zuliprc \\\n  --zulip-bot-config-file ~/.zuliprc-bot\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGemini CLI / Claude Desktop / Cursor\u003c/b\u003e\u003c/summary\u003e\n\nAdd to your MCP config file:\n\n```json\n{\n  \"mcpServers\": {\n    \"zulipchat\": {\n      \"command\": \"uvx\",\n      \"args\": [\"zulipchat-mcp\", \"--zulip-config-file\", \"/path/to/zuliprc\"]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGetting your zuliprc\u003c/b\u003e\u003c/summary\u003e\n\nDownload from Zulip: **Settings** \u003e **Personal settings** \u003e **Account \u0026 privacy** \u003e **API key**\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eConfiguration options\u003c/b\u003e\u003c/summary\u003e\n\n| Option | Description |\n|--------|-------------|\n| `--zulip-config-file PATH` | Path to your primary zuliprc |\n| `--zulip-bot-config-file PATH` | Optional bot zuliprc for dual identity |\n| `--unsafe` | Enable administrative tools (use with caution) |\n| `--debug` | Enable debug logging (outputs to stderr) |\n| `--enable-listener` | Enable background message listener service |\n\u003c/details\u003e\n\n## Documentation\n\n### For Users\n- [Installation Guide](docs/user-guide/installation.md) - Step-by-step setup instructions\n- [Quick Start Tutorial](docs/user-guide/quick-start.md) - Get running in minutes\n- [Configuration Reference](docs/user-guide/configuration.md) - All configuration options\n- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions\n\n### For Developers\n- [Architecture Overview](docs/developer-guide/architecture.md) - System design and components\n- [Tool Categories](docs/developer-guide/tool-categories.md) - Tool organization and patterns\n- [Foundation Components](docs/developer-guide/foundation-components.md) - Core building blocks\n- [Testing Guide](docs/testing/README.md) - Testing strategies and coverage\n\n### API Reference\n- [Messaging Tools](docs/api-reference/messaging.md) - Message operations documentation\n- [Stream Tools](docs/api-reference/streams.md) - Stream management APIs\n- [Event Tools](docs/api-reference/events.md) - Real-time event handling\n- [User Tools](docs/api-reference/users.md) - User and identity management\n- [Search Tools](docs/api-reference/search.md) - Search and analytics APIs\n- [File Tools](docs/api-reference/files.md) - File operations reference\n\n## Additional Resources\n\n### MCP Resources\nAccess Zulip data directly in your AI assistant:\n- `zulip://stream/{name}` - Stream message history\n- `zulip://streams` - All available streams\n- `zulip://users` - Organization users\n\n### Smart Prompts\nBuilt-in prompts for common tasks:\n- `daily_summary` - Comprehensive daily report\n- `morning_briefing` - Overnight activity summary\n- `catch_up` - Quick summary of recent messages\n\n## Troubleshooting\n\n**\"No Zulip email found\"**\n- Set the environment variables shown in Quick Start\n- Or create a config file in `~/.config/zulipchat-mcp/config.json`\n\n**\"Connection failed\"**\n- Verify your API key is correct\n- Check your Zulip site URL includes `https://`\n- Ensure your bot has permissions for the streams\n\n**\"Module not found\"**\n- Update uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n- Reinstall: `uvx --from git+https://github.com/akougkas/zulipchat-mcp.git zulipchat-mcp`\n\n## Common Use Cases\n\n- **DevOps**: Automate deployment notifications and incident updates\n- **Support**: Route customer questions and create ticket summaries\n- **Product**: Generate sprint reports and feature request digests\n- **Team Leads**: Daily standups and team activity summaries\n- **HR**: Onboarding workflows and announcement automation\n\n\n## 🤝 Contributing\n\nWe welcome contributions from everyone! Whether you're fixing bugs, adding features, or improving docs.\n\n📖 See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete guide.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔧 Development\u003c/b\u003e - For contributors\u003c/summary\u003e\n\n## Development\n\n### Prerequisites\n- Python 3.10+\n- [uv](https://docs.astral.sh/uv/) package manager (required - we use uv exclusively)\n\n### Local Setup\n```bash\ngit clone https://github.com/akougkas/zulipchat-mcp.git\ncd zulipchat-mcp\nuv sync\n\n# Run locally with zuliprc\nuv run zulipchat-mcp --zulip-config-file ~/.zuliprc\n```\n\n### Testing Connection\n```bash\nuv run python -c \"\nfrom src.zulipchat_mcp.core.client import ZulipClientWrapper\nfrom src.zulipchat_mcp.config import ConfigManager\nconfig = ConfigManager()\nclient = ZulipClientWrapper(config)\nprint(f'Connected! Identity: {client.identity_name}')\n\"\n```\n\n### Quality Checks\n```bash\n# Run before pushing\nuv run pytest -q                  # Tests (85% coverage required)\nuv run ruff check .               # Linting\nuv run black .                    # Formatting\nuv run mypy src                   # Type checking\n\n# Optional security checks\nuv run bandit -q -r src\nuv run safety check\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🏗️ Architecture\u003c/b\u003e - Technical details\u003c/summary\u003e\n\n## Architecture\n\n### Core Structure\n```\nsrc/zulipchat_mcp/\n├── core/           # Core business logic (client, exceptions, security, commands)\n├── utils/          # Shared utilities (health, logging, metrics, database)\n├── services/       # Background services (scheduler)\n├── tools/          # MCP tool implementations (messaging, streams, search, events, users, files)\n├── integrations/   # AI client integrations (Claude Code, Cursor, etc.)\n└── config.py       # Configuration management\n```\n\n### Technology Stack\n- [FastMCP](https://github.com/jlowin/fastmcp) - High-performance MCP server framework\n- [DuckDB](https://duckdb.org) - Embedded analytics database for persistence\n- [Pydantic](https://pydantic.dev) - Data validation and serialization\n- [UV](https://docs.astral.sh/uv/) - Ultra-fast Python package management\n- Async-first architecture for optimal performance\n- Smart caching with automatic invalidation\n- Comprehensive error handling and monitoring\n\n\u003c/details\u003e\n\nFor AI coding agents:\n- [AGENTS.md](AGENTS.md) - Repository guidelines and commands\n- [CLAUDE.md](CLAUDE.md) - Claude Code specific instructions\n\n## Privacy Policy\n\nThis MCP server is designed with privacy as a core principle:\n\n- **No data collection**: This server does not collect, store, or transmit any user data to third parties\n- **Local execution**: All processing happens locally on your machine\n- **Zulip API only**: The server only communicates with your configured Zulip instance using your provided credentials\n- **No telemetry**: No analytics, tracking, or usage data is collected\n- **Credential handling**: API keys and credentials are only used to authenticate with your Zulip server and are never logged or transmitted elsewhere\n\nFor the full privacy policy, see [PRIVACY.md](PRIVACY.md).\n\n## License\n\nMIT - See [LICENSE](LICENSE) for details.\n\n\u003c!-- mcp-name: io.github.akougkas/zulipchat --\u003e\n\n## Links\n\n- [Zulip API Documentation](https://zulip.com/api/)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [Report Issues](https://github.com/akougkas/zulipchat-mcp/issues)\n\n## Community\n\n### Code of Conduct\nWe're committed to providing a welcoming and inclusive experience for everyone. We expect all participants to:\n- Be respectful and collaborative\n- Assume positive intent\n- Provide constructive feedback\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md#our-values--code-of-conduct) for our full code of conduct.\n\n### Getting Help\n- 📖 Check the [documentation](docs/README.md)\n- 🐛 [Report issues](https://github.com/akougkas/zulipchat-mcp/issues)\n- 💬 Start a [discussion](https://github.com/akougkas/zulipchat-mcp/discussions)\n- 🤝 Read [CONTRIBUTING.md](CONTRIBUTING.md) to get involved\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003csub\u003eBuilt with ❤️ for the Zulip community by contributors around the world\u003c/sub\u003e\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakougkas%2Fzulipchat-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakougkas%2Fzulipchat-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakougkas%2Fzulipchat-mcp/lists"}