Zulip

🚀 Zulip MCP Server

The MCP (Machine Context Protocol) server for Zulip supports the Zulip API, enabling AI assistants like Claude to interact with Zulip workspaces.

🛠️ Tools

1. zulip_list_channels

   • Lists available channels (streams) in the organization.
   • Optional inputs:
     • include_private (boolean, default: false): Whether to include private streams.
     • include_web_public (boolean, default: true): Whether to include streams public to the web.
     • include_subscribed (boolean, default: true): Whether to include streams the bot is subscribed to.
   • Returns: A list of streams with IDs and information.

2. zulip_post_message

   • Publishes a new message to a Zulip channel (stream).
   • Required inputs:
     • channel_name (string): The name of the stream to publish to.
     • topic (string): The topic within the stream.
     • content (string): The content of the message to publish.
   • Returns: Confirmation of message publication and ID.

3. zulip_send_direct_message

   • Sends a direct message to one or more users.
   • Required inputs:
     • recipients (string[]): The email addresses or user IDs of the recipients.
     • content (string): The content of the message to send.
   • Returns: Confirmation of message sending and ID.

4. zulip_add_reaction

   • Adds an emoji reaction to a message.
   • Required inputs:
     • message_id (number): The ID of the message to reply to.
     • emoji_name (string): The name of the emoji without colons.
   • Returns: Confirmation of the reaction.

5. zulip_get_channel_history

   • Retrieves recent messages from a channel (stream) and topic.
   • Required inputs:
     • channel_name (string): The name of the stream.
     • topic (string): The name of the topic.
   • Optional inputs:
     • limit (number, default: 20): The number of messages to retrieve.
     • anchor (string, default: "newest"): The ID of the starting point message.
   • Returns: A list of messages with content and metadata.

6. zulip_get_topics

   • Gets the list of topics in a channel (stream).
   • Required input:
     • channel_name (string): The name of the stream.
   • Returns: Confirmation of the operation.

7. zulip_join_channel

   • Joins a channel.
   • Required input:
     • channel_name (string): The name of the stream to join.
   • Returns: Confirmation of joining the channel.

8. zulip_leave_channel

   • Leaves a channel.
   • Required input:
     • channel_name (string): The name of the stream to leave.
   • Returns: Confirmation of leaving the channel.

🛠️ Setup

Create a Zulip Bot

1. Log in to your Zulip organization.
2. Visit the Zulip management page.
3. Click the "Create new bot" button.
4. Configure the bot settings, such as the bot name and email address.
5. Generate and record the API key.

Configure Permissions

Ensure the bot has the following permissions:

• Read permission: Allows the bot to view channel content.
• Write permission: Allows the bot to send messages.
• Management permission (optional): Allows the bot to manage other users or channels.

💻 Usage Examples

Integrate with Claude Desktop

Run with npx

Run the following command in the terminal:

npx mcp-server zulip --url YOUR_ZULIP_URL --token YOUR_API_KEY

Run with Docker

Build the image and run the container:

docker build -t mcp/zulip .
docker run -it --rm mcp/zulip --url YOUR_ZULIP_URL --token YOUR_API_KEY

Configuration Examples

npx Method

Edit the claude_desktop_config.json file and add the following content:

{
  "mcpServers": [
    {
      "command": "npx",
      "args": ["mcp-server", "zulip"],
      "env": {
        "ZULIP_URL": "https://your-org.zulip.com",
        "ZULIP_TOKEN": "your_api_key_here"
      }
    }
  ]
}

Docker Method

Edit the claude_desktop_config.json file and add the following content:

{
  "mcpServers": [
    {
      "command": "docker",
      "args": ["run", "-it", "--rm", "mcp/zulip"],
      "env": {
        "ZULIP_URL": "https://your-org.zulip.com",
        "ZULIP_TOKEN": "your_api_key_here"
      }
    }
  ]
}

🚧 Troubleshooting

When encountering permission errors, please check:

1. Ensure the API key is correct.
2. Confirm that the bot has subscribed to the channels it needs to access.
3. Ensure the Zulip URL is correct and accessible.

🔨 Build

Build the Docker image using the following command:

docker build -t mcp/zulip .

📄 License

This MCP server is distributed under the MIT License.