Zulip MCP Server

Zulip MCP サーバー

LLM 向けのツールとして、Zulip REST API の機能を公開する Model Context Protocol（MCP）サーバーです。このサーバーを使用すると、AI アシスタントが Zulip ワークスペースをプログラムから操作できます。

機能

🔄 リソース（コンテキストデータ）

• ユーザーディレクトリ：役割やステータスを含む組織メンバーを参照できます
• ストリームディレクトリ：利用可能なストリームと権限を確認できます
• メッセージ形式ガイド：Zulip の Markdown 構文を網羅したリファレンスです
• 組織情報：サーバー設定、ポリシー、カスタム絵文字を確認できます
• ユーザーグループ：メンションや権限に利用できるグループを確認できます

🛠️ ツール（利用可能なアクション：25 種類）

ヘルパーツール（LLM 向けの検出）

• search-users - DM を送信する前に名前やメールアドレスでユーザーを検索します
• get-started - 接続をテストし、ワークスペースの概要を取得します

メッセージ操作

• send-message - ストリームまたはダイレクトメッセージに送信します
• get-messages - 高度なフィルタリングと検索を使ってメッセージを取得します
• get-message - 特定のメッセージの詳細情報を取得します
• upload-file - ファイルや画像を共有します
• edit-message - 内容を変更したり、トピックを移動したりします
• delete-message - メッセージを削除します（管理者権限が必要です）
• get-message-read-receipts - メッセージを読んだユーザーを確認します
• add-emoji-reaction - Unicode 絵文字またはカスタム絵文字でリアクションします
• remove-emoji-reaction - メッセージから絵文字リアクションを削除します

予約済みメッセージと下書き

• create-scheduled-message - 後で送信するメッセージを予約します
• edit-scheduled-message - 予約済みメッセージを編集します
• create-draft - 新しいメッセージの下書きを作成します
• get-drafts - 保存済みの下書きを取得します
• edit-draft - 下書きの内容を更新します

ストリーム管理

• get-subscribed-streams - ユーザーが登録しているストリームの一覧を取得します
• get-stream-id - 名前からストリーム ID を取得します
• get-stream-by-id - ストリームの詳細情報を取得します
• get-topics-in-stream - 最近のトピックを参照します

ユーザー操作

• get-users - 組織メンバーの一覧を取得します
• get-user-by-email - メールアドレスからユーザーを検索します
• get-user - ID からユーザーの詳細情報を取得します
• update-status - ステータスメッセージと在席状況を設定します
• get-user-groups - 利用可能なユーザーグループの一覧を取得します

📝 Zulip の用語：ストリームとチャンネル

Zulip では、**「ストリーム」と「チャンネル」**は同じものを指します。

• ストリーム = Zulip の正式な用語（API、ツール、インターフェースで使用）
• チャンネル = Slack／Discord／Teams で一般的に使われる用語
• 同じもの = チームがトピックについて話し合う会話スペース

この MCP サーバーでは、Zulip の公式ドキュメントと API に合わせて「ストリーム」という用語を使用しています。

インストールとセットアップ

前提条件

• npm を備えた Node.js 18 以降
• TypeScript 5 以降
• Zulip インスタンスへのアクセス（例：https://your-organization.zulipchat.com）
• Zulip API 認証情報（ボットトークンまたは API キー）

クイックスタート

1. クローンして依存関係をインストールします：

git clone <repository-url>
cd zulip-mcp-server
npm install

2. 環境変数を設定します：

cp .env.example .env
# Edit .env with your Zulip credentials

3. ビルドして実行します：

npm run build
npm start

環境設定

Zulip の認証情報を記載した .env ファイルを作成します。

ZULIP_URL=https://your-organization.zulipchat.com
[email protected]
ZULIP_API_KEY=your-api-key-here
NODE_ENV=production

Zulip API 認証情報の取得

1. ボットアクセスの場合（推奨）：

   • Zulip 組織の設定に移動します
   • 「Bots」セクションを開きます
   • 新しいボットを作成するか、既存のボットを使用します
   • ボットのメールアドレスと API キーをコピーします

2. 個人アクセスの場合：

   • 「Personal Settings」→「Account & Privacy」に移動します
   • 「API key」セクションを探します
   • API キーを生成するか、表示します

Claude Desktop との連携

この MCP サーバーを Claude Desktop で使用するには、Claude Desktop の設定ファイルに次の設定を追加します。

オプション 1：環境変数を使用する（推奨）

Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "[email protected]", 
        "ZULIP_API_KEY": "your-api-key-here"
      }
    }
  }
}

オプション 2：.env ファイルを使用する

.env ファイルを使用する場合は、プロジェクトディレクトリ内に配置し、次の設定を使用します。

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "cwd": "/path/to/zulip-mcp-server"
    }
  }
}

Claude Desktop の設定ファイルの場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

Cursor との連携

この MCP サーバーを Cursor IDE で使用するには、Cursor の MCP 設定に次の内容を追加します。

Cursor MCP の設定

Cursor の MCP 設定ファイル（ワークスペース内の .cursor-mcp/config.json またはグローバル設定）に追加します。

{
  "mcpServers": {
    "zulip": {
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "[email protected]",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      "capabilities": {
        "tools": true,
        "resources": true
      }
    }
  }
}

Cursor MCP の設定場所：

• ワークスペース：プロジェクトのルートにある .cursor-mcp/config.json
• グローバル：プラットフォーム固有の Cursor 設定ディレクトリ

Raycast MCP 拡張機能

Raycast でこの MCP サーバーを使用するには、MCP 拡張機能の設定で構成します。

Raycast MCP の設定

Raycast MCP 拡張機能の設定に追加します。

{
  "servers": {
    "zulip": {
      "name": "Zulip Integration",
      "description": "Send messages and interact with Zulip workspace",
      "command": "node",
      "args": ["/path/to/zulip-mcp-server/dist/server.js"],
      "env": {
        "ZULIP_URL": "https://your-organization.zulipchat.com",
        "ZULIP_EMAIL": "[email protected]",
        "ZULIP_API_KEY": "your-api-key-here"
      },
      "icon": "💬",
      "categories": ["communication", "productivity"]
    }
  }
}

Raycast の設定手順：

1. Raycast MCP 拡張機能をインストールします
2. Raycast の環境設定 → 拡張機能 → MCP を開きます
3. 新しいサーバー設定を追加します
4. 上記の JSON 設定を貼り付けます
5. パスと認証情報を必要に応じて更新します

Raycast の使用方法：

• ⌘ + Space を使って Raycast を開きます
• 「Zulip」コマンドを検索します
• Raycast のインターフェースから MCP ツールを直接実行します

対応 MCP クライアント

このサーバーは、MCP に準拠したあらゆるクライアントと互換性があります。検証済みの連携は次のとおりです。

プラットフォーム	設定の種類	状態	使用方法
Claude Desktop	JSON 設定	✅ 検証済み	Zulip と連携した AI との会話
Cursor IDE	ワークスペース／グローバル設定	✅ 検証済み	Zulip の通知に対応したコードエディター
Raycast	拡張機能の設定	✅ 検証済み	クイックコマンドと自動化
その他の MCP クライアント	標準 MCP プロトコル	🔄 互換性あり	MCP に準拠したあらゆるアプリケーション

汎用 MCP コマンド：

node /path/to/zulip-mcp-server/dist/server.js

開発

スクリプト

npm run dev          # Development with hot reload
npm run build        # Build for production
npm test            # Run tests
npm run lint        # Lint TypeScript
npm run typecheck   # Type checking

プロジェクト構成

src/
├── server.ts        # Main MCP server
├── zulip/
│   └── client.ts    # Zulip API client
└── types.ts         # TypeScript definitions

テスト

MCP Inspector を使ってサーバーをテストします。

npx @modelcontextprotocol/inspector npm start

使用例

メッセージの送信

// Send to a stream
await callTool("send-message", {
  type: "stream",
  to: "general",
  topic: "Daily Standup",
  content: "Good morning team! 👋\n\n**Today's Goals:**\n- Review PR #123\n- Deploy feature X"
});

// Direct message
await callTool("send-message", {
  type: "direct",
  to: "[email protected]",
  content: "Hey! Can you review the latest changes when you have a moment?"
});

メッセージの取得

// Get recent messages from a stream
await callTool("get-messages", {
  narrow: [["stream", "general"], ["topic", "announcements"]],
  num_before: 50
});

// Search messages
await callTool("get-messages", {
  narrow: [["search", "deployment"], ["sender", "[email protected]"]]
});

ストリームの管理

// List subscribed streams
await callTool("get-subscribed-streams", {
  include_subscribers: true
});

// Get stream topics
await callTool("get-topics-in-stream", {
  stream_id: 123
});

Markdown の書式設定サポート

このサーバーには、包括的な書式設定ガイドのリソースが含まれています。Zulip では次の機能がサポートされています。

• 標準的な Markdown：太字、斜体、コード、リンク、リスト
• メンション：@**Full Name**（通知）、@_**Name**_（サイレント）
• ストリームリンク：#**stream-name**
• コードブロック：シンタックスハイライト付き
• 数式：$$math$$ を使った LaTeX の数式
• ネタバレ：||hidden content||
• カスタム絵文字：組織固有の絵文字

エラー処理

このサーバーは、包括的なエラー処理を提供します。

• ネットワーク接続の問題
• 認証の失敗
• 権限エラー
• レート制限
• 無効なパラメーター
• Zulip API エラー

すべてのエラーには、デバッグに役立つメッセージが含まれます。

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 新しい機能のテストを追加します
4. TypeScript のコンパイルが通ることを確認します
5. プルリクエストを送信します

サポート

問題や質問がある場合：

• Zulip API のドキュメントを確認します：https://zulip.com/api/
• MCP の仕様を確認します：https://modelcontextprotocol.io/
• バグや機能リクエストについては、GitHub イシューを作成します