avisekrath/zulip-mcp-server

Zulip MCP Server

A Model Context Protocol (MCP) server that exposes Zulip REST API capabilities as tools for LLMs. This server allows AI assistants to interact with your Zulip workspace programmatically.

Features

🔄 Resources (Contextual Data)

• User Directory: Browse organization members with roles and status
• Stream Directory: Explore available streams and permissions
• Message Formatting Guide: Complete Zulip markdown syntax reference
• Organization Info: Server settings, policies, and custom emoji
• User Groups: Available groups for mentions and permissions

🛠️ Tools (25 Available Actions)

Helper Tools (LLM-Friendly Discovery)

• search-users - Find users by name/email before sending DMs
• get-started - Test connection and get workspace overview

Message Operations

• send-message - Send to streams or direct messages
• get-messages - Retrieve with advanced filtering and search
• get-message - Get detailed information about specific message
• upload-file - Share files and images
• edit-message - Modify content or move topics
• delete-message - Remove messages (admin permissions required)
• get-message-read-receipts - Check who read messages
• add-emoji-reaction - React with Unicode or custom emoji
• remove-emoji-reaction - Remove emoji reactions from messages

Scheduled Messages & Drafts

• create-scheduled-message - Schedule future messages
• edit-scheduled-message - Modify scheduled messages
• create-draft - Create new message drafts
• get-drafts - Retrieve saved drafts
• edit-draft - Update draft content

Stream Management

• get-subscribed-streams - List user's stream subscriptions
• get-stream-id - Get stream ID by name
• get-stream-by-id - Detailed stream information
• get-topics-in-stream - Browse recent topics

User Operations

• get-users - List organization members
• get-user-by-email - Find users by email
• get-user - Get detailed user information by ID
• update-status - Set status message and availability
• get-user-groups - List available user groups

📝 Zulip Terminology: Streams vs Channels

In Zulip, "streams" and "channels" refer to the same concept:

• Stream = Official Zulip terminology (used in API, tools, interface)
• Channel = Common term from Slack/Discord/Teams
• Same thing = Conversation spaces where teams discuss topics

This MCP server uses "stream" to match Zulip's official documentation and API.

Installation & Setup

Prerequisites

• Node.js 18+ with npm
• TypeScript 5+
• Access to a Zulip instance (e.g., https://your-organization.zulipchat.com)
• Zulip API credentials (bot token or API key)

Quick Start

1. Clone and install dependencies:

git clone <repository-url>
cd zulip-mcp-server
npm install

2. Configure environment variables:

cp .env.example .env
# Edit .env with your Zulip credentials

3. Build and run:

npm run build
npm start

Environment Configuration

Create a .env file with your Zulip credentials:

ZULIP_URL=https://your-organization.zulipchat.com
ZULIP_EMAIL=your-bot-email@yourcompany.com
ZULIP_API_KEY=your-api-key-here
NODE_ENV=production

Getting Zulip API Credentials

1. For Bot Access (Recommended):

   • Go to your Zulip organization settings
   • Navigate to "Bots" section
   • Create a new bot or use existing one
   • Copy the bot email and API key

2. For Personal Access:

   • Go to Personal Settings → Account & Privacy
   • Find "API key" section
   • Generate or reveal your API key

Claude Desktop Integration

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:

Option 1: Using Environment Variables (Recommended)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "your-bot-email@yourcompany.com", 
        "ZULIP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Using .env File

If you prefer using a .env file, ensure it's in the project directory and use:

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "cwd": "/path/to/zulip-mcp-server"
    }
  }
}

Claude Desktop Config Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor Integration

To use this MCP server with Cursor IDE, add the following to your Cursor MCP settings:

Cursor MCP Configuration

Add to Cursor's MCP settings file (.cursor-mcp/config.json in your workspace or global settings):

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "your-bot-email@yourcompany.com",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      "capabilities": {
        "tools": true,
        "resources": true
      }
    }
  }
}

Cursor MCP Config Location:

• Workspace: .cursor-mcp/config.json in your project root
• Global: Platform-specific Cursor settings directory

Raycast MCP Extension

To use this MCP server with Raycast, configure it in the MCP extension settings:

Raycast MCP Configuration

Add to Raycast MCP extension configuration:

{
  "servers": {
    "zulip": {
      "name": "Zulip Integration",
      "description": "Send messages and interact with Zulip workspace",
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "your-bot-email@yourcompany.com",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      "icon": "💬",
      "categories": ["communication", "productivity"]
    }
  }
}

Raycast Setup Steps:

1. Install the Raycast MCP extension
2. Open Raycast preferences → Extensions → MCP
3. Add new server configuration
4. Paste the JSON configuration above
5. Update paths and credentials accordingly

Raycast Usage:

• Use ⌘ + Space to open Raycast
• Search for "Zulip" commands
• Execute MCP tools directly from Raycast interface

Supported MCP Clients

This server is compatible with any MCP-compliant client. Here are the verified integrations:

Universal MCP Command:

node /path/to/zulip-mcp-server/dist/server.js

Development

Scripts

npm run dev          # Development with hot reload
npm run build        # Build for production
npm test            # Run tests
npm run lint        # Lint TypeScript
npm run typecheck   # Type checking

Project Structure

src/
├── server.ts        # Main MCP server
├── zulip/
│   └── client.ts    # Zulip API client
└── types.ts         # TypeScript definitions

Testing

Test the server using MCP Inspector:

npx @modelcontextprotocol/inspector npm start

Usage Examples

Sending Messages

// Send to a stream
await callTool("send-message", {
  type: "stream",
  to: "general",
  topic: "Daily Standup",
  content: "Good morning team! 👋\n\n**Today's Goals:**\n- Review PR #123\n- Deploy feature X"
});

// Direct message
await callTool("send-message", {
  type: "direct",
  to: "user@example.com",
  content: "Hey! Can you review the latest changes when you have a moment?"
});

Getting Messages

// Get recent messages from a stream
await callTool("get-messages", {
  narrow: [["stream", "general"], ["topic", "announcements"]],
  num_before: 50
});

// Search messages
await callTool("get-messages", {
  narrow: [["search", "deployment"], ["sender", "admin@example.com"]]
});

Stream Management

// List subscribed streams
await callTool("get-subscribed-streams", {
  include_subscribers: true
});

// Get stream topics
await callTool("get-topics-in-stream", {
  stream_id: 123
});

Markdown Formatting Support

The server includes a comprehensive formatting guide resource. Zulip supports:

• Standard Markdown: Bold, italic, code, links, lists
• Mentions: @**Full Name** (notify), @_**Name**_ (silent)
• Stream Links: #**stream-name**
• Code Blocks: With syntax highlighting
• Math: LaTeX expressions with $$math$$
• Spoilers: ||hidden content||
• Custom Emoji: Organization-specific emoji

Error Handling

The server provides comprehensive error handling:

• Network connectivity issues
• Authentication failures
• Permission errors
• Rate limiting
• Invalid parameters
• Zulip API errors

All errors include helpful messages for debugging.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure TypeScript compilation passes
5. Submit a pull request

Support

For issues and questions:

• Check Zulip API documentation: https://zulip.com/api/
• Review MCP specification: https://modelcontextprotocol.io/
• Open GitHub issues for bugs or feature requests