在Zulip中运行AI代理作为@mentionable机器人——或者连接到任何MCP客户端。也可以作为Python库使用。

快速开始

1. 安装该软件包：

2. 在你的项目根节点添加一个包含 Zulip 机器人凭证的文件 .zuliprc。关于如何制作机器人，请参见添加机器人或集成。机器人类型必须是“通用”的。

3. 将MCP服务器添加到你的.mcp.json：

4. 重启你的MCP客户端。Zulip工具现在应该可用了。

要求

• Python >=3.10，用 uv 管理
• 用于 Zulip API 认证的 .zuliprc 文件（见快速启动）
• 监听器模式：所选后端CLI默认安装并认证（claude，codex与--backend codex，或opencode为[--backend opencode）

入口点

图书馆使用

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,