home / mcp / zulip mcp server

Zulip MCP Server

unofficial zulip mcp server that allows LLMs like Claude to interact with your workspace & take actions on your behalf

Installation

Add the following to your MCP client configuration file.

Configuration

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

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
[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 → 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