Zulip MCP Server

MCP Server for the Zulip API, enabling AI assistants like Claude to interact with Zulip workspaces.

Tools

1. zulip_list_channels
2. List available channels (streams) in the Zulip organization
3. Optional inputs:
   • include_private (boolean, default: false): Whether to include private streams
   • include_web_public (boolean, default: true): Whether to include web-public streams
   • include_subscribed (boolean, default: true): Whether to include streams the bot is subscribed to

4. Returns: List of streams with their IDs and information

5. zulip_post_message

6. Post a new message to a Zulip channel (stream)
7. Required inputs:
   • channel_name (string): The name of the stream to post to
   • topic (string): The topic within the stream
   • content (string): The message content to post

8. Returns: Message posting confirmation and ID

9. zulip_send_direct_message

10. Send a direct message to one or more users
11. Required inputs:
    • recipients (string[]): Email addresses or user IDs of recipients
    • content (string): The message content to send

12. Returns: Message sending confirmation and ID

13. zulip_add_reaction

14. Add an emoji reaction to a message
15. Required inputs:
    • message_id (number): The ID of the message to react to
    • emoji_name (string): Emoji name without colons

16. Returns: Reaction confirmation

17. zulip_get_channel_history

18. Get recent messages from a channel (stream) and topic
19. Required inputs:
    • channel_name (string): The name of the stream
    • topic (string): The topic name
20. Optional inputs:
    • limit (number, default: 20): Number of messages to retrieve
    • anchor (string, default: "newest"): Message ID to start from

21. Returns: List of messages with their content and metadata

22. zulip_get_topics

23. Get topics in a channel (stream)
24. Required inputs:
    • channel_id (number): The ID of the stream

25. Returns: List of topics in the stream

26. zulip_subscribe_to_channel

27. Subscribe the bot to a channel (stream)
28. Required inputs:
    • channel_name (string): The name of the stream to subscribe to

29. Returns: Subscription confirmation

30. zulip_get_users

31. Get list of users in the Zulip organization
32. Returns: List of users with their basic information

Setup

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

7. Click "Create bot"

8. Permissions:

9. By default, Zulip bots have limited permissions
10. Make sure to subscribe the bot to any streams it needs to access

11. If you need the bot to have more permissions, consider using a full user account instead

12. Get the API credentials:

13. Bot's email address
14. Bot's API key (displayed when you create the bot)
15. Zulip instance URL (e.g., https://example.zulipchat.com)

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

npx

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

docker

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

Troubleshooting

If you encounter permission errors, verify that: 1. The bot API key is correct 2. The bot has been subscribed to the channels it needs to access 3. The Zulip URL is correct and accessible

Build

Docker build:

docker build -t mcp/zulip .

License

This MCP server is licensed under the MIT License.