# Zulip MCP Server

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

## Tools

1. `zulip_list_channels`
   - List available channels (streams) in the Zulip organization
   - 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
   - Returns: List of streams with their IDs and information

2. `zulip_post_message`
   - Post a new message to a Zulip channel (stream)
   - 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
   - Returns: Message posting confirmation and ID

3. `zulip_send_direct_message`
   - Send a direct message to one or more users
   - Required inputs:
     - `recipients` (string[]): Email addresses or user IDs of recipients
     - `content` (string): The message content to send
   - Returns: Message sending confirmation and ID

4. `zulip_add_reaction`
   - Add an emoji reaction to a message
   - Required inputs:
     - `message_id` (number): The ID of the message to react to
     - `emoji_name` (string): Emoji name without colons
   - Returns: Reaction confirmation

5. `zulip_get_channel_history`
   - Get recent messages from a channel (stream) and topic
   - Required inputs:
     - `channel_name` (string): The name of the stream
     - `topic` (string): The topic name
   - Optional inputs:
     - `limit` (number, default: 20): Number of messages to retrieve
     - `anchor` (string, default: "newest"): Message ID to start from
   - Returns: List of messages with their content and metadata

6. `zulip_get_topics`
   - Get topics in a channel (stream)
   - Required inputs:
     - `channel_id` (number): The ID of the stream
   - Returns: List of topics in the stream

7. `zulip_subscribe_to_channel`
   - Subscribe the bot to a channel (stream)
   - Required inputs:
     - `channel_name` (string): The name of the stream to subscribe to
   - Returns: Subscription confirmation

8. `zulip_get_users`
   - Get list of users in the Zulip organization
   - Returns: List of users with their basic information

## Setup

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

2. Permissions:
   - By default, Zulip bots have limited permissions
   - Make sure to subscribe the bot to any streams it needs to access
   - If you need the bot to have more permissions, consider using a full user account instead

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

### Usage with Claude Desktop

Add the following to your `claude_desktop_config.json`:

#### npx

```json
{
  "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

```json
{
  "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:

```bash
docker build -t mcp/zulip .
```

## License

Copyright 2025 Monadical

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

This product includes third-party software components. See the [LICENSE](LICENSE) and [NOTICE](NOTICE) files for details.