ZulipChat MCP Server

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

Quick Start

Get your AI assistant connected to Zulip in 30 seconds:

# Run setup wizard (recommended)
uvx --from zulipchat-mcp zulipchat-mcp-setup

Or manually with a zuliprc file:

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

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

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:

uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

uvx --from zulipchat-mcp zulipchat-mcp-setup

The wizard finds your zuliprc files, validates credentials, and generates MCP client config.

claude mcp add zulipchat -- uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

With dual identity (user + bot):

claude mcp add zulipchat -- uvx zulipchat-mcp \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

Add to your MCP config file:

{
  "mcpServers": {
    "zulipchat": {
      "command": "uvx",
      "args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/zuliprc"]
    }
  }
}

Download from Zulip: Settings > Personal settings > Account & privacy > API key

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

# Run locally with zuliprc
uv run zulipchat-mcp --zulip-config-file ~/.zuliprc

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 (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

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

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.

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