https://github.com/akougkas/zulipchat-mcp
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!
https://github.com/akougkas/zulipchat-mcp
ai-agent ai-integration automation fastmcp mcp messaging model-context-protocol zulip
Last synced: 4 months ago
JSON representation
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!
- Host: GitHub
- URL: https://github.com/akougkas/zulipchat-mcp
- Owner: akougkas
- License: mit
- Created: 2025-06-18T21:00:49.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-01-22T10:38:02.000Z (5 months ago)
- Last Synced: 2026-01-23T01:01:42.255Z (5 months ago)
- Topics: ai-agent, ai-integration, automation, fastmcp, mcp, messaging, model-context-protocol, zulip
- Language: Python
- Homepage:
- Size: 2.46 MB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# ZulipChat MCP Server
Connect your AI assistant to Zulip with 8 powerful tool categories via MCP
[](https://pypi.org/project/zulipchat-mcp/)
[](https://pypi.org/project/zulipchat-mcp/)
[](https://github.com/akougkas/zulipchat-mcp/stargazers)
[](https://github.com/akougkas/zulipchat-mcp/commits/main)
[](https://pypi.org/project/zulipchat-mcp/)
[](LICENSE)
[](https://modelcontextprotocol.io)
[🚀 Quick Start](#-quick-start) • [📦 Installation](#-installation) • [📚 Features](#-what-can-you-do) • [🛠️ Tools](#-available-tools) • [💡 Examples](#-real-world-examples) • [📖 Releases](#-releases) • [🤝 Contributing](CONTRIBUTING.md)
---
## Quick Start
Get your AI assistant connected to Zulip in **30 seconds**:
```bash
# Run setup wizard (recommended)
uvx --from zulipchat-mcp zulipchat-mcp-setup
```
Or manually with a zuliprc file:
```bash
uvx zulipchat-mcp --zulip-config-file ~/.zuliprc
```
## What Can You Do?
Your AI assistant becomes a **Zulip superuser**, capable of:
- **Intelligent Messaging** - Send, schedule, search, and manage messages with context awareness
- **Stream Management** - Create, configure, and analyze streams with engagement metrics
- **Real-time Monitoring** - React to events, track activity, and automate responses
- **Advanced Analytics** - Generate insights, sentiment analysis, and participation reports
- **File Operations** - Upload, share, and manage files with automatic distribution
- **Workflow Automation** - Chain complex operations with conditional logic
## Available Tools
40+ tools across 8 categories:
| Category | Count | Highlights |
|----------|-------|------------|
| **Messaging** | 12 | Send, edit, schedule, cross-post, reactions |
| **Streams** | 2 | List and query stream details |
| **Topics** | 2 | List topics, cross-stream operations |
| **Users** | 12 | Profiles, presence, groups, muting |
| **Search & Analytics** | 6 | Narrow filters, AI insights, summaries |
| **Events** | 4 | Queues, long-polling, webhooks |
| **Files** | 2 | Upload, share, manage |
| **System** | 6+ | Identity switching, workflows, chains |
View all tools by category
### Messaging Tools
- `message` - Send, schedule, or draft messages with smart formatting
- `search_messages` - Token-limited results with narrow filters
- `edit_message` - Edit content and topics with propagation modes
- `bulk_operations` - Progress tracking for bulk actions
- `message_history` - Audit trail with edit timestamps
- `cross_post_message` - Attribution-aware sharing across streams
- `add_reaction` / `remove_reaction` - Emoji support (Unicode, custom, Zulip)
- `mark_read` / `mark_unread` - Read state management
- `schedule_message` / `cancel_scheduled` - Delayed delivery
### Stream & Topic Tools
- `get_stream_info` - Stream details with subscriber lists
- `list_streams` - Filter by subscription status
- `list_topics` - Topics within a stream
- `manage_topics` - Cross-stream transfers with propagation
### User Tools
- `manage_users` - Multi-identity support (user/bot contexts)
- `switch_identity` - Session continuity with validation
- `manage_user_groups` - Group lifecycle and membership
- `get_presence` - User online status
- `set_status` - Status emoji and text
- `mute_user` / `unmute_user` - User muting
### Search & Analytics Tools
- `advanced_search` - Multi-faceted search with ranking
- `analytics` - AI-powered insights with sentiment analysis
- `get_daily_summary` - Activity summaries with engagement
### Event Tools
- `register_events` - 20+ event types with auto-cleanup
- `get_events` - Long-polling with queue validation
- `delete_queue` - Queue cleanup
- `listen_events` - Webhook integration
### File Tools
- `upload_file` - Progress tracking with auto-sharing
- `manage_files` - File lifecycle with metadata extraction
### System & Workflow Tools
- `server_info` - Server metadata with routing hints
- `tool_help` - On-demand documentation
- `execute_chain` - Workflow automation with branching logic
- `register_agent` - Agent session tracking
- `agent_message` - Bot identity messaging
## Installation
One command to connect your AI to Zulip:
```bash
uvx zulipchat-mcp --zulip-config-file ~/.zuliprc
```
Setup Wizard - guided configuration
```bash
uvx --from zulipchat-mcp zulipchat-mcp-setup
```
The wizard finds your zuliprc files, validates credentials, and generates MCP client config.
Claude Code
```bash
claude mcp add zulipchat -- uvx zulipchat-mcp --zulip-config-file ~/.zuliprc
```
With dual identity (user + bot):
```bash
claude mcp add zulipchat -- uvx zulipchat-mcp \
--zulip-config-file ~/.zuliprc \
--zulip-bot-config-file ~/.zuliprc-bot
```
Gemini CLI / Claude Desktop / Cursor
Add to your MCP config file:
```json
{
"mcpServers": {
"zulipchat": {
"command": "uvx",
"args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/zuliprc"]
}
}
}
```
Getting your zuliprc
Download from Zulip: **Settings** > **Personal settings** > **Account & privacy** > **API key**
Configuration options
| Option | Description |
|--------|-------------|
| `--zulip-config-file PATH` | Path to your primary zuliprc |
| `--zulip-bot-config-file PATH` | Optional bot zuliprc for dual identity |
| `--unsafe` | Enable administrative tools (use with caution) |
| `--debug` | Enable debug logging (outputs to stderr) |
| `--enable-listener` | Enable background message listener service |
## Documentation
### For Users
- [Installation Guide](docs/user-guide/installation.md) - Step-by-step setup instructions
- [Quick Start Tutorial](docs/user-guide/quick-start.md) - Get running in minutes
- [Configuration Reference](docs/user-guide/configuration.md) - All configuration options
- [Troubleshooting Guide](docs/TROUBLESHOOTING.md) - Common issues and solutions
### For Developers
- [Architecture Overview](docs/developer-guide/architecture.md) - System design and components
- [Tool Categories](docs/developer-guide/tool-categories.md) - Tool organization and patterns
- [Foundation Components](docs/developer-guide/foundation-components.md) - Core building blocks
- [Testing Guide](docs/testing/README.md) - Testing strategies and coverage
### API Reference
- [Messaging Tools](docs/api-reference/messaging.md) - Message operations documentation
- [Stream Tools](docs/api-reference/streams.md) - Stream management APIs
- [Event Tools](docs/api-reference/events.md) - Real-time event handling
- [User Tools](docs/api-reference/users.md) - User and identity management
- [Search Tools](docs/api-reference/search.md) - Search and analytics APIs
- [File Tools](docs/api-reference/files.md) - File operations reference
## Additional Resources
### MCP Resources
Access Zulip data directly in your AI assistant:
- `zulip://stream/{name}` - Stream message history
- `zulip://streams` - All available streams
- `zulip://users` - Organization users
### Smart Prompts
Built-in prompts for common tasks:
- `daily_summary` - Comprehensive daily report
- `morning_briefing` - Overnight activity summary
- `catch_up` - Quick summary of recent messages
## Troubleshooting
**"No Zulip email found"**
- Set the environment variables shown in Quick Start
- Or create a config file in `~/.config/zulipchat-mcp/config.json`
**"Connection failed"**
- Verify your API key is correct
- Check your Zulip site URL includes `https://`
- Ensure your bot has permissions for the streams
**"Module not found"**
- Update uv: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Reinstall: `uvx --from git+https://github.com/akougkas/zulipchat-mcp.git zulipchat-mcp`
## Common Use Cases
- **DevOps**: Automate deployment notifications and incident updates
- **Support**: Route customer questions and create ticket summaries
- **Product**: Generate sprint reports and feature request digests
- **Team Leads**: Daily standups and team activity summaries
- **HR**: Onboarding workflows and announcement automation
## 🤝 Contributing
We welcome contributions from everyone! Whether you're fixing bugs, adding features, or improving docs.
📖 See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete guide.
🔧 Development - For contributors
## Development
### Prerequisites
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) package manager (required - we use uv exclusively)
### Local Setup
```bash
git clone https://github.com/akougkas/zulipchat-mcp.git
cd zulipchat-mcp
uv sync
# Run locally with zuliprc
uv run zulipchat-mcp --zulip-config-file ~/.zuliprc
```
### Testing Connection
```bash
uv run python -c "
from src.zulipchat_mcp.core.client import ZulipClientWrapper
from src.zulipchat_mcp.config import ConfigManager
config = ConfigManager()
client = ZulipClientWrapper(config)
print(f'Connected! Identity: {client.identity_name}')
"
```
### Quality Checks
```bash
# Run before pushing
uv run pytest -q # Tests (85% coverage required)
uv run ruff check . # Linting
uv run black . # Formatting
uv run mypy src # Type checking
# Optional security checks
uv run bandit -q -r src
uv run safety check
```
🏗️ Architecture - Technical details
## Architecture
### Core Structure
```
src/zulipchat_mcp/
├── core/ # Core business logic (client, exceptions, security, commands)
├── utils/ # Shared utilities (health, logging, metrics, database)
├── services/ # Background services (scheduler)
├── tools/ # MCP tool implementations (messaging, streams, search, events, users, files)
├── integrations/ # AI client integrations (Claude Code, Cursor, etc.)
└── config.py # Configuration management
```
### Technology Stack
- [FastMCP](https://github.com/jlowin/fastmcp) - High-performance MCP server framework
- [DuckDB](https://duckdb.org) - Embedded analytics database for persistence
- [Pydantic](https://pydantic.dev) - Data validation and serialization
- [UV](https://docs.astral.sh/uv/) - Ultra-fast Python package management
- Async-first architecture for optimal performance
- Smart caching with automatic invalidation
- Comprehensive error handling and monitoring
For AI coding agents:
- [AGENTS.md](AGENTS.md) - Repository guidelines and commands
- [CLAUDE.md](CLAUDE.md) - Claude Code specific instructions
## Privacy Policy
This MCP server is designed with privacy as a core principle:
- **No data collection**: This server does not collect, store, or transmit any user data to third parties
- **Local execution**: All processing happens locally on your machine
- **Zulip API only**: The server only communicates with your configured Zulip instance using your provided credentials
- **No telemetry**: No analytics, tracking, or usage data is collected
- **Credential handling**: API keys and credentials are only used to authenticate with your Zulip server and are never logged or transmitted elsewhere
For the full privacy policy, see [PRIVACY.md](PRIVACY.md).
## License
MIT - See [LICENSE](LICENSE) for details.
## Links
- [Zulip API Documentation](https://zulip.com/api/)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [Report Issues](https://github.com/akougkas/zulipchat-mcp/issues)
## Community
### Code of Conduct
We're committed to providing a welcoming and inclusive experience for everyone. We expect all participants to:
- Be respectful and collaborative
- Assume positive intent
- Provide constructive feedback
See [CONTRIBUTING.md](CONTRIBUTING.md#our-values--code-of-conduct) for our full code of conduct.
### Getting Help
- 📖 Check the [documentation](docs/README.md)
- 🐛 [Report issues](https://github.com/akougkas/zulipchat-mcp/issues)
- 💬 Start a [discussion](https://github.com/akougkas/zulipchat-mcp/discussions)
- 🤝 Read [CONTRIBUTING.md](CONTRIBUTING.md) to get involved
---
Built with ❤️ for the Zulip community by contributors around the world