zulipmcp

Run AI agents in Zulip as @mentionable bots — or wire into any MCP client. Also works as a Python library.

Quickstart

1. Install the package:

   uv add zulipmcp --git https://github.com/windborne/zulipmcp.git
   

2. Add a .zuliprc file to your project root with your Zulip bot credentials. See Add a bot or integration for instructions on making a bot. The bot type must be “generic.”

3. Add the MCP server to your .mcp.json:

   {
     "mcpServers": {
       "zulip": {
         "command": "uv",
         "args": ["run", "python", "-m", "zulipmcp.mcp"]
       }
     }
   }
   

4. Restart your MCP client. The Zulip tools should now be available.

Requirements

• Python >=3.10, managed with uv
• A .zuliprc file for Zulip API auth (see Quickstart)
• For listener mode: the selected backend CLI installed and authenticated (claude by default, codex with --backend codex, or opencode with --backend opencode)

Entry Points

Library Usage

zulipmcp can also be imported directly as a Python library:

import zulipmcp

# Fetch and format recent messages
messages = zulipmcp.get_messages(hours_back=24, channels=["engineering"])
print(zulipmcp.format_messages(messages))

# Send a message
zulipmcp.send_message("engineering", "general", "Hello from Python!")

# Configure MCP hooks before starting the server
zulipmcp.configure(
    message_prefix=lambda: "[bot] ",
    on_session_end=lambda session: print(f"Session ended in #{session.stream}"),
)

Hermes Gateway

Hermes uses the native hermes_plugin/zulip gateway adapter instead of the subprocess listener. Each stream/topic maps to its own persistent Hermes session, while zulipmcp remains available as the explicit Zulip API tool layer.

• Mention the bot once to activate a topic; follow-ups do not need a mention.
• Each user message is a fresh Hermes turn with a fresh iteration budget.
• Typing, normal response delivery, status reactions, approval reactions,