ZulipChat MCP Server

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

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

{
  "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"
      }
    }
  }
}

{
  "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

{
  "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"
      }
    }
  }
}

{
  "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

• Release Notes
• Release Documentation
• Full Changelog

Previous Versions

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

⚙️ Configuration Guide

Configuration Parameters

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.

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

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}')
"

# 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

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

For AI coding agents:

• AGENTS.md - Repository guidelines and commands
• CLAUDE.md - Claude Code specific instructions

License

MIT - See LICENSE for details.

Links

• Zulip API Documentation
• Model Context Protocol
• Report 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 for our full code of conduct.

Getting Help

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