ZulipChat MCP Server

ZulipChat MCP サーバー

---

クイックスタート

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

このコマンドを MCP クライアントで設定すると、アシスタントが設定済みのアカウントで Zulip のメッセージを読み書きできるようになります。

zuliprc が必要ですか? Zulip Settings > Personal > Account & privacy > API key — ファイルをダウンロードし、~/.zuliprc として保存してください。

対話形式のオンボーディング:

uvx --from zulipchat-mcp zulipchat-mcp-setup

できること

ZulipChat MCP は、MCP 互換のあらゆる AI アシスタント(Claude Code、Gemini CLI、Cursor、Windsurf など)をあなたの Zulip ワークスペースに橋渡しします。アシスタントは次のことができます:

• メッセージの送受信 — ストリームメッセージ、DM、返信、リアクション
• 会話履歴の検索 — 送信者、ストリーム、期間でフィルタリングできる全文検索
• 名前による相手の特定 — 送信前に一意の宛先を確認し、曖昧な名前は確認を求めます
• ID の切り替え — 同じセッション内で、自分としてもボットとしても投稿できます
• アクティビティの監視 — 最近のメッセージの検索、ストリーム情報の取得、オンライン状況の確認
• セッションを Zulip トピックに紐付け — 長時間実行されるエージェントセッションに安定したコントロールトピックを付与します
• 通常のボットメンションを受信 — イベント駆動のローカル受信箱を独自のホストアダプターがポーリングし、会話に /reply を使わずにエージェントを起動して元のトピックに返信できます。サーバーはトランスポートであり、コーディングエージェントの起動や監視は行いません
• 日付付きスナップショットの再利用 — 短命なメッセージキャッシュとレートを考慮したリクエスト受付により、繰り返しの API 読み取りを削減します
• トピック内での承認リクエスト — オーナーがセッショントピックで /approve REQUEST_ID または /deny REQUEST_ID と返信します。各判断は、それが応答するリクエストを明示します
• Agent Skills の読み込み — メッセージング、セッション制御、通知、制限付きワークループ向けの 4 つのパッケージ済み指示を、ローカルファイルおよび MCP リソースとして利用できます
• エージェントパッケージのエクスポート — ネイティブのホスト設定とスキル、Claude のフック/プラグインアセット、または Agent Plugins 1.0.0 パッケージ

エージェントのセットアップ

# Substitute another supported client as needed.
uvx --from zulipchat-mcp zulipchat-mcp-integrate export --client clio-coder \
  --output-dir /absolute/path/to/project \
  --zulip-config-file /absolute/path/to/.zuliprc --extended-tools

エクスポートは claude-code、codex、opencode、copilot、vscode、 antigravity-cli、clio-coder、generic をサポートしています。パッケージには --mode plugin を追加してください。 複数の Zulip 組織がある場合は、組織ごとに --server-id zulipchat-<org> を指定して 1 回ずつエクスポートします。エクスポートは 1 つのホスト設定にマージされます。 アカウントの状態は ~/.local/state/zulipchat-mcp/ に保存されます。ホストの信頼は明示的なままです。 Clio は MCP の実行をプラグインの内容とは別に設定します。詳しくは ケイパビリティマトリクス、 Clio ガイド、 ワークフロー全体をご覧ください。

読み取り専用アクセスには --tool-profile read-only を追加します。ディスカバリと実行の 両方で、9 個のコア読み取りまたは 23 個の拡張読み取りが公開されます。デフォルトの フルプロファイルでは 20/60 個のツールが維持されます。キャッシュの鮮度、レート制限、 メッセージ転送とホスト実行の境界については API カバレッジと効率をご覧ください。 Luna のライブ実験では、非公開で未出荷の ホストアダプターによって駆動される実際の Clio TUI からの、通常のメンションからボットへの 返信が記録されています。その他のホストは、ライブセッションではなく、エクスポートされた 設定と偽の認証情報によるチェックを通じてテストされました。

2 層のツールアーキテクチャ

v0.6.0 では意図的な分割が導入されました。デフォルトで 20 個のコアツール、さらに必要になったときに 60 個のツールです。

コアモード (デフォルト)

日常的な用途のほとんどをカバーする 20 個のツール:

カテゴリ	ツール
メッセージング	send_message, edit_message, get_message, add_reaction
検索	search_messages, get_streams, get_stream_info, get_stream_topics
ユーザー	resolve_user, get_users, get_own_user
エージェント通信	teleport_chat, register_agent, ensure_agent_session, agent_message, request_user_input, wait_for_response
システム	switch_identity, server_info, manage_message_flags

なぜ 60 ではなく 20 なのでしょうか? ツールが少ないほど、ツールの選択が速くなり、トークンのオーバーヘッドが減り、AI の混乱も少なくなります。メッセージの送信、検索、リアクション、エージェントセッションの Zulip へのバインドなど、ほとんどのタスクはコアセットだけで済みます。

拡張モード

スケジュールされたメッセージ、イベントキュー、ファイルアップロード、分析、高度な検索が必要ですか?

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, get_drafts, create_draft, edit_draft, delete_draft, 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

ライフサイクルと承認ルーティングのためのオプションの Claude フックブリッジ:

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

プロジェクトローカルのフック、スキル、サブエージェントのためのオプションの Claude パッケージエクスポート:

uvx --from zulipchat-mcp zulipchat-mcp-integrate export \
  --client claude-code \
  --mode standalone \
  --output-dir . \
  --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"]
    }
  }
}

設定オプション

オプション	説明
--zulip-config-file PATH	zuliprc ファイルへのパス
--zulip-bot-config-file PATH	デュアルアイデンティティ用のボット zuliprc
--extended-tools	20 個のコアツールセットではなく、60 個すべてのツールを登録します
--tool-profile {full,read-only}	検出をフィルタリングし、読み取り専用の Zulip 呼び出しを強制します。デフォルト: full
--transport {stdio,http}	サービスを提供するトランスポート (デフォルト: stdio)
--host HOST	HTTP トランスポートのバインドホスト (デフォルト: 127.0.0.1)
--port PORT	HTTP トランスポートのバインドポート (デフォルト: 8000)
--auth-token TOKEN	HTTP トランスポート用のベアラー認証トークン (または ZULIPCHAT_HTTP_AUTH_TOKEN)
--allowed-host HOST	追加の信頼できる HTTP ホスト名。複数の名前を指定するには繰り返します
--allowed-origin URL	追加の信頼できるブラウザーオリジン。複数のオリジンを指定するには繰り返します
--unsafe	管理ツールを有効にします (注意して使用してください)
--debug	デバッグログを有効にします
--associate-existing-db	未バインドのレガシーデータベースを、検証済みの現在のアカウントに意図的に関連付けます

リモート HTTP トランスポート

ZulipChat MCP は、MCP 2026-07-28 プロトコルに基づくステートレス HTTP デプロイメントをサポートしています:

# Run server over HTTP with bearer authentication
ZULIPCHAT_HTTP_AUTH_TOKEN=your-secret-token \
  uvx zulipchat-mcp --zulip-config-file ~/.zuliprc --transport http --host 0.0.0.0 --port 8000 --allowed-host mcp.internal

リモート HTTP 接続用のクライアント統合スニペットを生成します:

uvx --from zulipchat-mcp zulipchat-mcp-integrate print --client claude-code --remote-url http://mcp.internal:8000/mcp --remote-token your-secret-token

HTTP の起動では、非ループバックバインドにベアラートークンが必要であり、Host ヘッダーと Origin ヘッダーを検証します。クライアントまたはリバースプロキシが使用するホスト名に対して --allowed-host を設定してください。リモート接続ではプロキシで TLS を終端してください。トークンは設定された Zulip アカウントへのアクセスを許可します。無関係なユーザー間で共有するのではなく、信頼できるアカウントごとに個別のインスタンスをデプロイしてください。

HTTP ツールは、サーバーローカルのファイルパス、アウトバウンドイベントコールバック、および switch_identity を拒否します。テキストは file_content で、バイナリバイトは file_content_base64 でアップロードしてください。ダウンロードは download_path を指定せずに URL を取得します。ローカルファイル操作と実行時のアイデンティティ切り替えには stdio を使用してください。添付ファイルの削除には --unsafe が必要です。

永続状態はデフォルトでアカウントスコープのディレクトリになります。明示的に選択された ZULIPCHAT_DB_PATH は、正規化されたレルムとユーザー/ボットのプリンシパルに関連付けられます。別のアカウントでは再利用できません。レガシー状態はそのまま保持され、意図的な関連付けが必要です。詳細は データベースの移行 を参照してください。

エージェントセッション、承認、リスナーカーソル、およびデフォルトのバックグラウンドタスクストレージはローカル状態のままです。これらのワークフローには単一のインスタンスを使用してください。DuckDB パスを分けるとライターの競合は回避できますが、セッションデータは共有されません。そのようなレプリカ間での通常のラウンドロビンルーティングはサポートされていません。レガシー HTTP クライアントもトランスポートセッションを保持する場合があります。

AI 分析と LLM プロバイダー

AI を活用した分析ツール (analyze_stream_with_llm、analyze_team_activity_with_llm、intelligent_report_generator) は、サーバー側の Anthropic LLM プロバイダーを使用して実行されます:

• LLM 生成のために、サーバープロセスで ANTHROPIC_API_KEY を設定します。
• オプションで ANTHROPIC_MODEL を設定して、デフォルトモデル (claude-opus-5) を上書きできます。
• API キーがない場合、分析ツールは llm_unavailable: true を含む構造化データサマリーを返すため、クライアントのアシスタントがデータを直接分析できます。

その他のクライアント

専用のセットアップページ:

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

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

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

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

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

実際の使用例

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

「15時にデプロイすることをチームに伝えて」 → アシスタントが #engineering に告知を送るため send_message を呼び出します。

「API マイグレーションについてのあのメッセージは誰が送ったの？」 → アシスタントがキーワードで search_messages を呼び出し、送信者とコンテキストを返します。

「Sarah の最後のメッセージに :thumbs_up: でリアクションして」 → アシスタントが resolve_user（"Sarah"）、search_messages（送信者）を呼び出し、続いて add_reaction を実行します。

「PR の準備ができたと Jaime に DM して」 → アシスタントがあいまいな名前解決で teleport_chat を呼び出します — メールアドレスは不要です。

開発

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              # full test suite, 60% coverage gate
uv run ruff check .           # Linting
uv run mypy src               # Type checking

パッケージング、依存関係、FastMCP、または起動に関する変更については、リリーススモークを実行してください:

uv build
scripts/pre_release_smoke.sh --version X.Y.Z --allow-dirty

完全なガイドについては CONTRIBUTING.md を、AI エージェント向けの指示については CLAUDE.md / AGENTS.md を参照してください。

アーキテクチャ

src/zulipchat_mcp/
├── core/           # Client wrapper, identity, caching, security
├── tools/          # MCP tool implementations (two-tier registration)
├── services/       # Background listener and session event routing
├── utils/          # Logging, DuckDB persistence, metrics
└── config.py       # config loading (zuliprc + environment fallback)

FastMCP をベースにした非同期ファーストの設計で、エージェントの状態永続化に DuckDB を使用し、高速なあいまい解決のためのスマートなユーザー/ストリームキャッシュを備えています。

プライバシー

• データ収集なし — Zulip API 呼び出しを除き、お使いのマシンから何も送信されません
• テレメトリなし — 分析、トラッキング、利用状況レポートは一切ありません
• ローカル実行 — すべての処理はお使いのハードウェア上で行われます
• 認証情報はローカルに保持 — API キーがログに記録されたり、お使いの Zulip サーバー以外に送信されたりすることはありません

完全なポリシー: PRIVACY.md

ライセンス

MIT — LICENSE を参照

リンク

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

---