ZulipChat MCP Server

🚀 Quick Start • 📦 Installation • 📚 Features • 🛠️ Tools • 💡 Examples • 📖 Releases • 🤝 Contributing

Quick Start

Get your AI assistant connected to Zulip in 30 seconds:

# Basic setup (user credentials only)
uvx --from git+https://github.com/akougkas/zulipchat-mcp.git zulipchat-mcp \
  --zulip-email user@org.com \
  --zulip-api-key YOUR_API_KEY \
  --zulip-site https://org.zulipchat.com

Want advanced AI agent features? Add bot credentials:

uvx --from git+https://github.com/akougkas/zulipchat-mcp.git zulipchat-mcp \
  --zulip-email user@org.com \
  --zulip-api-key YOUR_API_KEY \
  --zulip-site https://org.zulipchat.com \
  --zulip-bot-email bot@org.com \
  --zulip-bot-api-key BOT_API_KEY

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

Category	Tools	Key Capabilities
📨 Messaging	8\| Tool \| Capabilities \|\|-------\|----------------\|\| `message` \| Send, schedule, or draft messages with smart formatting and delivery options \|\| `search_messages` \| Token-limited results with narrow filters and advanced queries \|\| `edit_message` \| Edit content + topics with propagation modes and notification control \|\| `bulk_operations` \| Progress tracking for bulk actions across multiple messages \|\| `message_history` \| Complete audit trail with edit timestamps and revision tracking \|\| `cross_post_message` \| Attribution-aware sharing across streams with context preservation \|\| `add_reaction` \| Emoji type support (Unicode, custom, Zulip extra) \|\| `remove_reaction` \| Emoji type support (Unicode, custom, Zulip extra) \|	Send, edit, search, bulk operations, reactions
📁 Streams & Topics	5\| Tool \| Capabilities \|\|-------\|----------------\|\| `manage_streams` \| Lifecycle management with permissions, bulk subscriptions \|\| `manage_topics` \| Cross-stream transfers with propagation modes and notifications \|\| `get_stream_info` \| Comprehensive details with subscriber lists and topic inclusion \|\| `stream_analytics` \| NEW! Growth trends, engagement metrics, subscriber activity \|\| `manage_stream_settings` \| NEW! Notification preferences, appearance, permissions \|	Lifecycle management, analytics, permissions
⚡ Real-time Events	3\| Tool \| Capabilities \|\|-------\|----------------\|\| `register_events` \| 20+ event types with auto-cleanup and queue management \|\| `get_events` \| Long-polling support with queue validation and error handling \|\| `listen_events` \| NEW! Webhook integration, event filtering, stateless operation \|	Event streams, webhooks, long-polling
👥 User Management	3\| Tool \| Capabilities \|\|-------\|----------------\|\| `manage_users` \| Multi-identity support (user/bot/admin contexts) \|\| `switch_identity` \| NEW! Session continuity with validation and capability tracking \|\| `manage_user_groups` \| NEW! Complete group lifecycle with membership management \|	Multi-identity, groups, profiles
🔍 Search & Analytics	3\| Tool \| Capabilities \|\|-------\|----------------\|\| `advanced_search` \| NEW! Multi-faceted search with intelligent ranking and aggregation \|\| `analytics` \| NEW! AI-powered insights with sentiment analysis and participation metrics \|\| `get_daily_summary` \| NEW! Comprehensive activity summaries with stream engagement \|	AI insights, sentiment, participation
📎 Files & Media	2\| Tool \| Capabilities \|\|-------\|----------------\|\| `upload_file` \| NEW! Progress tracking, auto-sharing, security validation \|\| `manage_files` \| NEW! Complete file lifecycle with metadata extraction \|	Upload, share, metadata extraction
🤖 Agent Communication	13\| Tool \| Capabilities \|\|-------\|----------------\|\| `register_agent` \| NEW! Database persistence with session tracking \|\| `agent_message` \| NEW! BOT identity messaging with AFK gating \|\| `request_user_input` \| NEW! Interactive workflows with intelligent routing \|\| `start_task` \| NEW! Full task lifecycle management \|\| `update_progress` \| NEW! Full task lifecycle management \|\| `complete_task` \| NEW! Full task lifecycle management \|\| `enable_afk_mode` \| NEW! Away-mode automation \|\| `disable_afk_mode` \| NEW! Away-mode automation \|\| ...and 5 more tools \| Advanced workflow automation and monitoring \|	Task tracking, AFK mode, workflows
⚙️ System & Workflow	6+\| Tool \| Capabilities \|\|-------\|----------------\|\| `server_info` \| NEW! Comprehensive metadata with routing hints \|\| `tool_help` \| NEW! On-demand documentation with module search \|\| `execute_chain` \| NEW! Sophisticated workflow automation with branching logic \|\| ...and 3+ more tools \| Identity policy, agent bootstrapping, command types \|	Chains, documentation, server info

Installation

Choose Your Installation Method

Option 1: From PyPI (Recommended - Coming Soon)

# Basic setup (mandatory parameters)
uvx zulipchat-mcp \
  --zulip-email user@org.com \
  --zulip-api-key YOUR_API_KEY \
  --zulip-site https://org.zulipchat.com

# With bot for AI agent features (add optional parameters)
uvx zulipchat-mcp \
  --zulip-email user@org.com \
  --zulip-api-key YOUR_API_KEY \
  --zulip-site https://org.zulipchat.com \
  --zulip-bot-email bot@org.com \
  --zulip-bot-api-key BOT_API_KEY

Option 2: From GitHub (Available Now)

# Basic setup
uvx --from git+https://github.com/akougkas/zulipchat-mcp.git zulipchat-mcp \
  --zulip-email user@org.com \
  --zulip-api-key YOUR_API_KEY \
  --zulip-site https://org.zulipchat.com

# With bot credentials
uvx --from git+https://github.com/akougkas/zulipchat-mcp.git zulipchat-mcp \
  --zulip-email user@org.com \
  --zulip-api-key YOUR_API_KEY \
  --zulip-site https://org.zulipchat.com \
  --zulip-bot-email bot@org.com \
  --zulip-bot-api-key BOT_API_KEY

Option 3: From Source (For Development)

git clone https://github.com/akougkas/zulipchat-mcp.git
cd zulipchat-mcp
uv sync

# Run with mandatory parameters
uv run zulipchat-mcp \
  --zulip-email user@org.com \
  --zulip-api-key YOUR_API_KEY \
  --zulip-site https://org.zulipchat.com

MCP Client Integration

Add to claude_desktop_config.json:

From PyPI (once published):

{
  "mcpServers": {
    "zulipchat": {
      "command": "uvx",
      "args": ["zulipchat-mcp"],
      "env": {
        "ZULIP_EMAIL": "bot@your-org.zulipchat.com",
        "ZULIP_API_KEY": "your-api-key",
        "ZULIP_SITE": "https://your-org.zulipchat.com"
      }
    }
  }
}

From GitHub (available now):

{
  "mcpServers": {
    "zulipchat": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/akougkas/zulipchat-mcp.git", "zulipchat-mcp"],
      "env": {
        "ZULIP_EMAIL": "bot@your-org.zulipchat.com",
        "ZULIP_API_KEY": "your-api-key",
        "ZULIP_SITE": "https://your-org.zulipchat.com"
      }
    }
  }
}

# From PyPI (once published)
claude mcp add zulipchat \
  -e ZULIP_EMAIL=bot@your-org.zulipchat.com \
  -e ZULIP_API_KEY=your-api-key \
  -e ZULIP_SITE=https://your-org.zulipchat.com \
  -- uvx zulipchat-mcp

# From GitHub (available now)
claude mcp add zulipchat \
  -e ZULIP_EMAIL=bot@your-org.zulipchat.com \
  -e ZULIP_API_KEY=your-api-key \
  -e ZULIP_SITE=https://your-org.zulipchat.com \
  -- uvx --from git+https://github.com/akougkas/zulipchat-mcp.git zulipchat-mcp

# From TestPyPI (for testing)
claude mcp add zulipchat \
  -e ZULIP_EMAIL=bot@your-org.zulipchat.com \
  -e ZULIP_API_KEY=your-api-key \
  -e ZULIP_SITE=https://your-org.zulipchat.com \
  -- uvx --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ zulipchat-mcp

Add to your mcp_config.json or similar editor specific mcp config file:

From PyPI (once published):

{
  "mcpServers": {
    "zulipchat": {
      "command": "uvx",
      "args": ["zulipchat-mcp"],
      "env": {
        "ZULIP_EMAIL": "bot@your-org.zulipchat.com",
        "ZULIP_API_KEY": "your-api-key",
        "ZULIP_SITE": "https://your-org.zulipchat.com"
      }
    }
  }
}

From GitHub (available now):

{
  "mcpServers": {
    "zulipchat": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/akougkas/zulipchat-mcp.git", "zulipchat-mcp"],
      "env": {
        "ZULIP_EMAIL": "bot@your-org.zulipchat.com",
        "ZULIP_API_KEY": "your-api-key",
        "ZULIP_SITE": "https://your-org.zulipchat.com"
      }
    }
  }
}

Real-World Examples

AI-Powered Analytics & Insights

You: "Show me engagement trends for #design this week with top contributors"
AI: Design Channel Analytics (7 days):
    • 40% increase in activity
    • 127 messages (+32% vs last week)
    • Top contributors: Alice (23), Bob (18), Carol (15)
    • Peak activity: Tuesday 2-4pm
    • Hot topics: accessibility (28%), mobile UX (22%)
    • Collaboration score: 9.2/10

Smart Workflow Automation

You: "Schedule weekly standup reminders for #engineering every Monday at 9am"
AI: Automated Standup System Created:
    • Scheduled: Every Monday 9:00 AM
    • Template: Previous week summary + upcoming milestones
    • Auto-includes: Sprint progress & blockers
    • Notifications: Team leads get preview 30min prior

Intelligent File Management

You: "Upload the new design mockups and share them in #design with context for review"
AI: File Upload & Distribution Complete:
    Uploaded: UI_Mockups_v3.2.pdf (4.2MB, 24 pages)
    Auto-detected: Figma export, includes mobile & desktop views
    Shared in #design with:
      • Design review request template
      • @design-leads tagged for approval
      • Comparison links to previous version
      • Review deadline: Next Friday

Advanced Search & Discovery

You: "Find all technical decisions made about authentication in the last month"
AI: Technical Decision Discovery:
    Found 8 authentication-related decisions:
    • OAuth 2.0 implementation (approved - #backend)
    • Multi-factor requirements (pending - #security)
    • Session timeout policies (implemented - #devops)
    • API key rotation (scheduled - #infrastructure)
    Full decision log exported to #documentation

Smart Daily Operations

You: "Generate our comprehensive daily standup for engineering with blockers and sentiment"
AI: Daily Engineering Standup Report:

    Yesterday's Accomplishments (12 contributors):
    • API endpoint refactoring completed (Alice, Bob)
    • Mobile UI bugs fixed (Carol, Dan)
    • Security audit findings addressed (Eve, Frank)

    Current Blockers (3 identified):
    • Database migration pending DBA review
    • Third-party API rate limits affecting tests
    • Design assets needed for new feature

    Team Sentiment: 85% positive
    Energy Level: High (sprint goals on track)
    Notable: Team excited about upcoming hackathon

    Sprint Progress: 68% complete (ahead of schedule)

Releases

Latest: v2.5.0 - Enhanced Credential Management

43+ tools with complete Zulip automation capabilities

Previous Versions

v1.5.0 - Project management features
v1.0.0 - Initial release

⚙️ Configuration Guide

Configuration Parameters

Parameter	Required	Description	Example
`--zulip-email`	Yes	Your Zulip user email	`user@org.com`
`--zulip-api-key`	Yes	Your Zulip API key	`abcd1234...`
`--zulip-site`	Yes	Your Zulip organization URL	`https://org.zulipchat.com`
`--zulip-bot-email`	No	Bot email for AI agent features	`bot@org.com`
`--zulip-bot-api-key`	No	Bot API key	`wxyz5678...`
`--zulip-bot-name`	No	Custom bot display name	`AI Assistant`
`--zulip-bot-avatar-url`	No	Bot avatar image URL	`https://...`

Environment Variables

export ZULIP_EMAIL="bot@zulip.com"
export ZULIP_API_KEY="your-key"
export ZULIP_SITE="https://org.zulipchat.com"

Config File

Create ~/.config/zulipchat-mcp/config.json:

{
  "email": "bot@zulip.com",
  "api_key": "your-key",
  "site": "https://org.zulipchat.com"
}

Documentation

For Users

Installation Guide - Step-by-step setup instructions
Quick Start Tutorial - Get running in minutes
Configuration Reference - All configuration options
Troubleshooting Guide - Common issues and solutions

For Developers

Architecture Overview - System design and components
Tool Categories - Tool organization and patterns
Foundation Components - Core building blocks
Testing Guide - Testing strategies and coverage

API Reference

Messaging Tools - Message operations documentation
Stream Tools - Stream management APIs
Event Tools - Real-time event handling
User Tools - User and identity management
Search Tools - Search and analytics APIs
File Tools - 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 for the complete guide.

Development

Prerequisites

Python 3.10+
uv package manager (required - we use uv exclusively)

Local Setup

git clone https://github.com/akougkas/zulipchat-mcp.git
cd zulipchat-mcp
uv sync

# Copy environment template (never commit secrets)
cp -n .env.example .env || true

# Run locally with credentials
uv run zulipchat-mcp \
  --zulip-email your@email.com \
  --zulip-api-key YOUR_KEY \
  --zulip-site https://yourorg.zulipchat.com

Testing Connection

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

# Run before pushing
uv run pytest -q                  # Tests (90% 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

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 - High-performance MCP server framework
DuckDB - Embedded analytics database for persistence
Pydantic - Data validation and serialization
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 - Repository guidelines and commands
CLAUDE.md - Claude Code specific instructions

License

MIT - See LICENSE for details.

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 for our full code of conduct.

Getting Help

📖 Check the documentation
🐛 Report issues
💬 Start a discussion
🤝 Read CONTRIBUTING.md to get involved

Zulip Chat