Zulipchat MCP

🚀 ZulipChat MCP Server

ZulipChat用のModel Context Protocolサーバーです。Claude Code、Gemini CLI、Codex、Cursor、Windsurf、VS Code CopilotなどのMCPクライアントをZulipに接続できます。

🚀 クイックスタート

uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

これだけです。AIアシスタントがZulipのメッセージを読み書きできるようになります。

zuliprcが必要ですか？ Zulip設定 > 個人設定 > アカウントとプライバシー > APIキー からファイルをダウンロードし、~/.zuliprcとして保存してください。

対話型のオンボーディングは以下のコマンドで実行できます。

uvx zulipchat-mcp-setup

✨ 主な機能

ZulipChat MCPは、MCP互換のAIアシスタント（Claude Code、Gemini CLI、Cursor、Windsurfなど）をZulipワークスペースに接続します。アシスタントは以下のことができます。

• メッセージの送受信 — ストリームメッセージ、DM、返信、リアクションを処理できます。
• 会話履歴の検索 — 送信者、ストリーム、時間範囲でフィルタリングした全文検索が可能です。
• 名前でユーザーを特定 — "message Jaime" のような指定で、正式なメールアドレスを探す必要がありません。
• アイデンティティの切り替え — 同じセッション内で自分自身またはボットとして投稿できます。
• アクティビティの監視 — 最近のメッセージを検索、ストリーム情報を取得、オンラインユーザーを確認できます。

二段階ツールアーキテクチャ

v0.6.0では、意図的に分割を導入しました。デフォルトでは19のコアツール、必要に応じて約55のツールを使用できます。

コアモード（デフォルト）

日常の95%の使用シーンをカバーする19のツールです。

なぜ19ツールなのか？ ツールが少ないほど、ツール選択が速く、トークンのオーバーヘッドが少なく、AIにとって混乱が少なくなります。ほとんどのタスク（メッセージの送信、検索、リアクション）にはコアセットで十分です。

拡張モード

スケジュールされたメッセージ、イベントキュー、ファイルアップロード、分析、高度な検索が必要な場合は、拡張モードを使用します。

uvx zulipchat-mcp --zulip-config-file ~/.zuliprc --extended-tools

または、環境変数を使用することもできます。

ZULIPCHAT_EXTENDED_TOOLS=1 uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

拡張モードでは以下のツールが追加されます。toggle_reaction, cross_post_message, advanced_search, construct_narrow, get_scheduled_messages, manage_scheduled_message, register_events, get_events, listen_events, upload_file, manage_files, get_daily_summary, manage_user_mute, get_user, get_presence, get_user_groups など。

📦 インストール

各クライアントの詳細なセットアップガイドは docs/integrations/README.md を参照してください。

Claude Code

claude mcp add zulipchat -- uvx zulipchat-mcp --zulip-config-file ~/.zuliprc

デュアルアイデンティティ（自分自身とボット）を使用する場合：

claude mcp add zulipchat -- uvx zulipchat-mcp \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

Gemini CLI

~/.gemini/settings.json の mcpServers の下に以下を追加します。

{
  "zulipchat": {
    "command": "uvx",
    "args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/.zuliprc"]
  }
}

Claude Desktop / Cursor / 任意のMCPクライアント

MCP設定に以下を追加します。

{
  "mcpServers": {
    "zulipchat": {
      "command": "uvx",
      "args": ["zulipchat-mcp", "--zulip-config-file", "/path/to/.zuliprc"]
    }
  }
}

設定オプション

その他のクライアント

専用のセットアップページがあります。

• Gemini CLI
• Codex
• OpenCode
• VS Code + GitHub Copilot
• Cursor
• Windsurf
• Antigravity
• 汎用MCP

デュアルアイデンティティ

ユーザーとボットの両方の zuliprc を設定することで、アシスタントがセッション中にアイデンティティを切り替えることができます。

uvx zulipchat-mcp \
  --zulip-config-file ~/.zuliprc \
  --zulip-bot-config-file ~/.zuliprc-bot

アシスタントはデフォルトであなたとして投稿します。switch_identity を呼び出すことで、ボットとして投稿できます。自動通知、エージェント間通信、または人間とボットのメッセージを区別するのに便利です。

💻 使用例

基本的な使用法

"今日の #engineering で何が起こったか教えて" → アシスタントが search_messages を呼び出し、ストリームと時間フィルターを適用してスレッドを要約します。

"チームに3時にデプロイすることを伝えて" → アシスタントが send_message を呼び出し、#engineering にアナウンスを投稿します。

"API移行に関するメッセージを誰が送ったの？" → アシスタントが search_messages を呼び出し、キーワードで検索し、送信者とコンテキストを返します。

"Sarahの最後のメッセージに 👍 でリアクションして" → アシスタントが resolve_user ("Sarah")、search_messages（送信者）を呼び出し、その後 add_reaction を呼び出します。

"JaimeにPRが準備できたことをDMで伝えて" → アシスタントが teleport_chat を呼び出し、曖昧な名前解決を使用してメールアドレスを必要とせずにDMを送信します。

開発

git clone https://github.com/akougkas/zulipchat-mcp.git
cd zulipchat-mcp
uv sync
uv run zulipchat-mcp --zulip-config-file ~/.zuliprc

チェックを実行するには：

uv run pytest -q              # 566 tests, 60% coverage gate
uv run ruff check .           # Linting
uv run mypy src               # Type checking

詳細なガイドは CONTRIBUTING.md を参照してください。AIエージェントの指示は CLAUDE.md / AGENTS.md を参照してください。

🔧 技術詳細

src/zulipchat_mcp/
├── core/           # クライアントラッパー、アイデンティティ、キャッシュ、セキュリティ
├── tools/          # MCPツールの実装（二段階登録）
├── services/       # バックグラウンドリスナー、AFKウォッチャー
├── utils/          # ロギング、DuckDB永続化、メトリクス
└── config.py       # 設定の読み込み（zuliprc + 環境変数のデフォルト）

このサーバーは FastMCP をベースに非同期優先設計で構築されており、エージェントの状態を永続化するために DuckDB を使用し、高速な曖昧な解決のためにスマートなユーザー/ストリームキャッシングを採用しています。

プライバシー

• データ収集なし — Zulip API呼び出し以外は何もあなたのマシンから送信されません。
• テレメトリなし — ゼロ分析、トラッキング、または使用状況報告です。
• ローカル実行 — すべての処理はあなたのハードウェア上で行われます。
• 資格情報はローカルに留まる — APIキーはログに記録されたり、あなたのZulipサーバーを超えて送信されることはありません。

詳細なポリシーは PRIVACY.md を参照してください。

📄 ライセンス

MITライセンスです。詳細は LICENSE を参照してください。

リンク

• ドキュメントインデックス
• サポート
• セキュリティポリシー
• Zulip APIドキュメント
• Model Context Protocol
• 問題の報告
• ディスカッション