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

Related MCP server: Zulip MCP Server

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

2. Configure environment variables:

3. Build and run:

Environment Configuration

Create a .env file with your Zulip credentials:

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:

Option 2: Using .env File

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

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

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:

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:

Development

Scripts

Project Structure

Testing

Test the server using MCP Inspector:

Usage Examples

Sending Messages

Getting Messages

Stream Management

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