Zulip

This Zulip MCP Server exposes Zulip REST API capabilities as tools for large language models. It lets AI assistants interact with your Zulip workspace programmatically by offering resource data (like user and stream directories) and a collection of actionable tools (sending messages, managing drafts, scheduling, and more).

How to use

Connect to the Zulip MCP Server with an MCP client to discover available resources and invoke tools. The server provides both discovery-style helpers (like searching users and testing the workspace) and practical actions (such as sending messages, retrieving messages, managing drafts, and handling streams). Use a compatible MCP client to browse resources, call tools, and compose multi-step workflows that interact with Zulip in a structured, model-friendly way.

Useful usage patterns include:

• Discovering users and streams to understand the workspace context before composing messages.
• Sending messages to streams or direct messages and including topics, attachments, or formatting.
• Reading messages with filters, performing searches, and checking read receipts.
• Scheduling messages and managing drafts to plan communications ahead of time.
• Browsing stream topics and subscribed streams to stay aligned with ongoing conversations.

How to install

Prerequisites include Node.js 18 or newer, npm, TypeScript 5+ and access to a Zulip instance with API credentials.

Step-by-step setup based on the repository's guidance:

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

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

npm run build
npm start

Additional configuration and notes

Environment variables required to connect to Zulip from the MCP server are listed in the example below. Create a .env file or provide values through your environment as shown in the Claude Desktop integration example.

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 → Bots, create or select a bot, then copy the bot email and API key.
2. For Personal Access: Go to Personal Settings → Account & Privacy, find API key, and generate or reveal your key.

## Claude Desktop, Cursor, and Raycast integration notes

To connect this MCP server with Claude Desktop, Cursor IDE, or Raycast, you configure an MCP server entry that points to the compiled server. The examples show a standard pattern where the MCP server is started with Node and the path to the built server is provided as an argument.

Example universal command to run the server locally (as shown in the README):

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

## Supported MCP Clients

This server is compatible with any MCP-compliant client. Verified integrations include Claude Desktop, Cursor IDE, Raycast, and other MCP clients.

## Development

Key development scripts are provided for development, building, testing, and linting.

npm run dev npm run build npm test npm run lint npm run typecheck

## Usage examples

The README provides example tool calls for sending and retrieving messages, as well as stream management tasks. These illustrate how to compose tool calls to interact with Zulip resources and perform common actions.

## Available tools

### send-message

Send a message to a Zulip stream or direct message with optional formatting and topics

### get-messages

Retrieve messages with filters, search, and narrowing options

### get-message

Get detailed information about a specific message

### upload-file

Share files and images with messages

### edit-message

Edit message content or move topics

### delete-message

Delete messages (admin permissions required)

### get-message-read-receipts

Check who read messages

### add-emoji-reaction

Add a Unicode or custom emoji reaction to a message

### remove-emoji-reaction

Remove emoji reactions from messages

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

### get-subscribed-streams

List streams the user is subscribed to

### get-stream-id

Get a stream ID by name

### get-stream-by-id

Get detailed information about a stream by ID

### get-topics-in-stream

Browse topics within a stream

### get-users

List organization members

### get-user-by-email

Find users by email

### get-user

Get detailed user information by ID

### update-status

Set a user’s status message and availability

### get-user-groups

List available user groups