akougkas/zulipchat-mcp

ZulipChat MCP Server

🚀 Quick Start

One-line Installation

curl -sSL https://raw.githubusercontent.com/akougkas2030/zulipchat-mcp/main/scripts/install.sh | bash

Docker Compose

version: '3.8'
services:
  zulipchat-mcp:
    image: akougkas2030/zulipchat-mcp:latest
    environment:
      - ZULIP_EMAIL=${ZULIP_EMAIL}
      - ZULIP_API_KEY=${ZULIP_API_KEY}
      - ZULIP_SITE=${ZULIP_SITE}
    ports:
      - "3000:3000"

Quick Docker Run

docker run -d \
  --name zulipchat-mcp \
  -e ZULIP_EMAIL="your-bot@zulip.com" \
  -e ZULIP_API_KEY="your-api-key" \
  -e ZULIP_SITE="https://your-org.zulipchat.com" \
  -p 3000:3000 \
  akougkas2030/zulipchat-mcp:latest

📋 Features

• 🔌 MCP Compatible - Works with Claude Desktop, Continue, and other MCP clients
• 🐳 Cross-Platform - Runs on Linux, macOS, and Windows via Docker
• 🔐 Secure - Multiple authentication methods, no hardcoded credentials
• 📨 Full Zulip API - Send messages, create streams, manage subscriptions
• 📊 Analytics - Daily summaries, activity reports, and catch-up features
• 🎯 Smart Prompts - Built-in templates for team communication workflows

Available Tools

Available Resources

• messages://stream_name - Recent messages from specific streams
• streams://all - Complete streams directory
• users://all - Organization user directory

Custom Prompts

• summarize - End-of-day summary with statistics
• prepare - Morning briefing with highlights
• catch_up - Quick summary of missed messages

🔧 Configuration

Method 1: Environment Variables

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

Method 2: Configuration File

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

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

Method 3: Docker Secrets (Production)

# Create secrets
echo "your-api-key" | docker secret create zulip_api_key -
echo "your-bot@zulip.com" | docker secret create zulip_email -
echo "https://your-org.zulipchat.com" | docker secret create zulip_site -

# Use in docker-compose.yml
docker-compose up -d

🔑 Getting Your API Key

Step 1: Log into your Zulip organization

Visit your Zulip organization (e.g., https://your-org.zulipchat.com)

Step 2: Navigate to Settings

• Click your profile picture in the top right
• Select "Personal settings"

Step 3: Generate API Key

• Go to the "Account & privacy" tab
• Scroll to "API key" section
• Click "Generate API key"
• Copy the key and your email

For detailed instructions with screenshots, see our .

🔌 MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zulipchat": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "akougkas2030/zulipchat-mcp:latest"],
      "env": {
        "ZULIP_EMAIL": "your-bot@zulip.com",
        "ZULIP_API_KEY": "your-api-key",
        "ZULIP_SITE": "https://your-org.zulipchat.com"
      }
    }
  }
}

Continue IDE

Add to your MCP configuration:

{
  "zulipchat": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "akougkas2030/zulipchat-mcp:latest"],
    "env": {
      "ZULIP_EMAIL": "your-bot@zulip.com",
      "ZULIP_API_KEY": "your-api-key",
      "ZULIP_SITE": "https://your-org.zulipchat.com"
    }
  }
}

🛠️ Development

Local Installation

# Clone repository
git clone https://github.com/akougkas2030/zulipchat-mcp.git
cd zulipchat-mcp

# Install with uv
uv sync

Running Tests

# Install with development dependencies
uv sync

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/zulipchat_mcp

Building Docker Image

# Build locally
docker build -t zulipchat-mcp .

# Test the build
docker run --rm zulipchat-mcp uv run python -c "from src.zulipchat_mcp import __version__; print(__version__)"

🌐 Platform Support

📖 Documentation

• - Detailed installation instructions
• - How to get your Zulip API key
• Docker Hub - Official container registry

🐳 Docker Hub

The ZulipChat MCP server is available on Docker Hub with multi-architecture support:

• Repository: akougkas2030/zulipchat-mcp
• Platforms: linux/amd64, linux/arm64
• Tags: latest, 1.0.0, and all version releases

Pull the latest version:

docker pull akougkas2030/zulipchat-mcp:latest

🚨 Troubleshooting

Common Issues

Connection Failed

# Check your credentials
docker run --rm -e ZULIP_SITE="..." -e ZULIP_EMAIL="..." -e ZULIP_API_KEY="..." \
  akougkas2030/zulipchat-mcp:latest uv run python -c \
  "from src.zulipchat_mcp.config import ConfigManager; ConfigManager().validate_config()"

Permission Denied

• Ensure your API key has the necessary permissions
• Check that your bot user has access to the streams you're trying to access

Docker Issues

# Check if container is running
docker ps

# View logs
docker logs zulipchat-mcp

# Restart container
docker restart zulipchat-mcp

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Run tests: pytest
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

This project is built on the shoulders of amazing open source projects:

• Model Context Protocol (MCP) - The foundation that makes AI-to-service integration possible
• Zulip - Outstanding open source team chat platform with excellent API
• FastMCP - Simplified MCP server framework
• uv - Blazing fast Python package management from Astral
• Pydantic - Data validation and settings management using Python type annotations
• Docker - Containerization platform enabling consistent deployments

Special thanks to the entire open source community that makes projects like this possible!

🔗 Related Projects

• MCP Official Documentation
• Zulip API Documentation
• Claude Desktop
• Continue IDE