Zulip MCP server

The Zulip MCP Server enables AI assistants like Claude to interact with Zulip workspaces through the Zulip API. It provides tools for reading messages, posting content, managing reactions, and more—allowing AI systems to participate in Zulip conversations.

Available Tools

Messaging Tools

• zulip_post_message: Post messages to channels
• zulip_send_direct_message: Send private messages to users
• zulip_add_reaction: Add emoji reactions to messages

Channel Management

• zulip_list_channels: List available streams in the organization
• zulip_get_topics: Retrieve topics within a channel
• zulip_get_channel_history: Get recent messages from a channel/topic
• zulip_subscribe_to_channel: Subscribe the bot to a channel

User Information

• zulip_get_users: Retrieve list of users in the organization

Setup Instructions

1. Create a Zulip Bot

1. Log in to your Zulip instance
2. Navigate to Settings > Personal > Bots
3. Click "Add a new bot"
4. Select "Generic bot" type
5. Fill in the required information
6. Click "Create bot"

2. Collect API Credentials

After creating your bot, you'll need:

• The bot's email address
• The bot's API key (displayed when you create the bot)
• Your Zulip instance URL (e.g., https://example.zulipchat.com)

3. Configure Permissions

• By default, Zulip bots have limited permissions
• Subscribe the bot to any streams it needs to access
• For greater permissions, consider using a full user account instead

Usage Configuration

Using with Claude Desktop

Add the Zulip MCP server to your claude_desktop_config.json using one of the following options:

Using NPX

{
  "mcpServers": {
    "zulip": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-zulip"
      ],
      "env": {
        "ZULIP_EMAIL": "[email protected]",
        "ZULIP_API_KEY": "your-bot-api-key",
        "ZULIP_URL": "https://example.zulipchat.com"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "zulip": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ZULIP_EMAIL",
        "-e",
        "ZULIP_API_KEY",
        "-e",
        "ZULIP_URL",
        "mcp/zulip"
      ],
      "env": {
        "ZULIP_EMAIL": "[email protected]",
        "ZULIP_API_KEY": "your-bot-api-key",
        "ZULIP_URL": "https://example.zulipchat.com"
      }
    }
  }
}

Troubleshooting

If you encounter permission errors, verify that:

• The bot API key is correct
• The bot has been subscribed to the channels it needs to access
• The Zulip URL is correct and accessible

Usage Examples

Posting a Message to a Channel

{
  "channel_name": "general",
  "topic": "Announcements",
  "content": "Hello everyone, this is a test message from the Zulip bot!"
}

Getting Channel History

{
  "channel_name": "engineering",
  "topic": "Current Sprint",
  "limit": 10
}

Sending a Direct Message

{
  "recipients": ["[email protected]", "[email protected]"],
  "content": "Hello! This is a private message from the Zulip bot."
}

Adding a Reaction

{
  "message_id": 123456,
  "emoji_name": "thumbs_up"
}

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.