What is Zulip Mcp Server

The zulip-mcp-server is an unofficial Model Context Protocol (MCP) server that allows AI assistants to programmatically interact with Zulip workspaces using the Zulip REST API.

Use cases

Use cases include automating message sending, managing user statuses, scheduling messages, retrieving organization member information, and integrating AI tools for better interaction within Zulip.

How to use

To use zulip-mcp-server, you need to clone the repository, install the necessary dependencies (Node.js and TypeScript), and set up access to a Zulip instance with valid API credentials. After setup, you can utilize various tools and resources provided by the server.

Key features

Key features include a user directory, channel directory, message formatting guide, organization info, user groups, and 19 available actions such as sending messages, retrieving messages, managing channels, and user operations.

Where to use

zulip-mcp-server can be used in any organization that utilizes Zulip for team communication, particularly in environments that leverage AI assistants for enhanced productivity.

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
[email protected]
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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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:

Platform	Config Type	Status	Usage
Claude Desktop	JSON config	✅ Verified	AI conversations with Zulip integration
Cursor IDE	Workspace/Global config	✅ Verified	Code editor with Zulip notifications
Raycast	Extension config	✅ Verified	Quick commands and automation
Other MCP Clients	Standard MCP protocol	🔄 Compatible	Any MCP-compliant application

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: "[email protected]",
  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", "[email protected]"]]
});

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