Webex MCP

webex-mcp

メンテナーの方は、GitHub Releases と npm の設定について、リリースの公開をご覧ください。

Cisco Webex Messaging 向け MCP サーバーです。AI アシスタントを Webex のスペース、メッセージ、ユーザーに接続します。

stdio 経由で Webex Messaging のツールを公開する、最小限の MCP サーバーです。Cursor、Claude Desktop、Codex、Claude Code、OpenCode、その他の MCP クライアントで動作します。

特長

• Webex Messaging の主要 API を幅広くカバー：スペース、メッセージ、メンバーシップ、ユーザー、チーム、Webhook、添付ファイルの操作、ファイルのダウンロード
• エージェント向けの受信添付ファイル対応：画像のインライン表示、テキストのページ分割表示、ZIP/JAR の内容一覧、あらゆるファイルのローカルディスクへの保存
• キーワードによるスペースとメッセージの検索（クライアント側でスキャン）
• webex-node SDK による Bearer トークン認証と、一部のエンドポイントでの REST フォールバック
• OAuth 2.0 Integration ログインと自動トークン更新

必要条件

• Node.js >= 18
• Webex Bot アクセストークン、または Webex Integration（OAuth）— developer.webex.com

クイックスタート

オプション A — Bot トークン

# Run via npx (recommended)
npx -y @yuryev89/webex-mcp@latest --token YOUR_ACCESS_TOKEN

# Or install globally
npm install -g @yuryev89/webex-mcp
webex-mcp --token YOUR_ACCESS_TOKEN

オプション B — OAuth Integration

# 1. Set credentials (or use a .env file in your working directory)
export WEBEX_CLIENT_ID="your-client-id"
export WEBEX_CLIENT_SECRET="your-client-secret"

# 2. Authenticate once (opens browser)
npx -y @yuryev89/webex-mcp@latest login

# 3. Start MCP server (reads saved tokens, auto-refreshes)
npx -y @yuryev89/webex-mcp@latest

Cursor の設定

Bot トークン

{
  "mcpServers": {
    "webex": {
      "command": "bash",
      "args": [
        "-lc",
        "npx -y @yuryev89/webex-mcp@latest --token \"$WEBEX_ACCESS_TOKEN\""
      ],
      "env": {
        "WEBEX_ACCESS_TOKEN": "YOUR_BOT_ACCESS_TOKEN"
      }
    }
  }
}

OAuth Integration

{
  "mcpServers": {
    "webex": {
      "command": "npx",
      "args": ["-y", "@yuryev89/webex-mcp@latest"],
      "env": {
        "WEBEX_CLIENT_ID": "YOUR_CLIENT_ID",
        "WEBEX_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}

Cursor を起動する前に（WEBEX_CLIENT_ID と WEBEX_CLIENT_SECRET を設定した状態で）、一度 npx -y @yuryev89/webex-mcp@latest login を実行してください。

Codex の設定

次のいずれかの設定を ~/.codex/config.toml に追加します（既存の設定があれば統合してください）。

Bot トークン

[mcp_servers.webex]
command = "npx"
args = ["-y", "@yuryev89/webex-mcp@latest"]

[mcp_servers.webex.env]
WEBEX_ACCESS_TOKEN = "YOUR_BOT_ACCESS_TOKEN"

OAuth Integration

先にオプション B — OAuth Integrationを完了し、その後、次の設定を使用します。

[mcp_servers.webex]
command = "npx"
args = ["-y", "@yuryev89/webex-mcp@latest"]

[mcp_servers.webex.env]
WEBEX_CLIENT_ID = "YOUR_CLIENT_ID"
WEBEX_CLIENT_SECRET = "YOUR_CLIENT_SECRET"

または、シェル環境に認証情報を保持し、[mcp_servers.webex] 内の [mcp_servers.webex.env] テーブルを env_vars = ["WEBEX_ACCESS_TOKEN"] に置き換えます（OAuth の場合は ["WEBEX_CLIENT_ID", "WEBEX_CLIENT_SECRET"]）。そのシェルから Codex を起動してください。

codex mcp list を実行して登録を確認し、Codex で /mcp を使って稼働中のサーバーを確認します。

リファレンス：Codex MCP のドキュメント。

Claude Code の設定

次のコマンドは、プロジェクトを問わずユーザーアカウントに Webex を登録します。認証方式を選択してください。

Bot トークン

claude mcp add --scope user \
  --env WEBEX_ACCESS_TOKEN=YOUR_BOT_ACCESS_TOKEN \
  --transport stdio webex -- npx -y @yuryev89/webex-mcp@latest

OAuth Integration

先にオプション B — OAuth Integrationを完了し、その後、登録します。

claude mcp add --scope user \
  --env WEBEX_CLIENT_ID=YOUR_CLIENT_ID \
  --env WEBEX_CLIENT_SECRET=YOUR_CLIENT_SECRET \
  --transport stdio webex -- npx -y @yuryev89/webex-mcp@latest

接続を確認するには、claude mcp list または claude mcp get webex を実行します。Claude Code 内では、/mcp を使ってステータスとツールを確認できます。認証方式を切り替えるには、claude mcp remove --scope user webex で既存のエントリーを削除してから、再登録してください。

リファレンス：Claude Code MCP のドキュメント。

OpenCode の設定

次の例のいずれかを、プロジェクト内の opencode.json、またはすべてのプロジェクトに適用する場合は ~/.config/opencode/opencode.json に統合します。

Bot トークン

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "webex": {
      "type": "local",
      "command": ["npx", "-y", "@yuryev89/webex-mcp@latest"],
      "enabled": true,
      "environment": {
        "WEBEX_ACCESS_TOKEN": "{env:WEBEX_ACCESS_TOKEN}"
      }
    }
  }
}

OpenCode の起動前に、環境変数として WEBEX_ACCESS_TOKEN を設定してください。{env:...} はその変数を読み取ります。

OAuth Integration

先にオプション B — OAuth Integrationを完了し、その後、次の設定を使用します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "webex": {
      "type": "local",
      "command": ["npx", "-y", "@yuryev89/webex-mcp@latest"],
      "enabled": true,
      "environment": {
        "WEBEX_CLIENT_ID": "{env:WEBEX_CLIENT_ID}",
        "WEBEX_CLIENT_SECRET": "{env:WEBEX_CLIENT_SECRET}"
      }
    }
  }
}

OpenCode の起動時に WEBEX_CLIENT_ID と WEBEX_CLIENT_SECRET を環境変数として設定しておいてください。サーバーを確認するには、opencode mcp list を実行します。

リファレンス：OpenCode MCP のドキュメントおよび設定。

クライアントの設定に関する注意事項

• 各クライアントはサーバーをローカルの stdio プロセスとして起動します。別のサーバーターミナルや HTTP URL は必要ありません。
• OAuth ログインは npx -y @yuryev89/webex-mcp@latest login で処理します。クライアントと同じ OS ユーザーおよびトークンストアの設定で実行してください。クライアントに組み込まれた MCP OAuth ログインコマンドでは、この手順の代わりになりません。
• OAuth を使用する場合は、クライアント設定、継承された環境、および読み込まれた .env から WEBEX_ACCESS_TOKEN を削除してください。静的トークンは保存済みの OAuth トークンより優先されます。
• 認証情報のプレースホルダーはローカルで置き換えてください。実際の認証情報をバージョン管理に含めないでください。CLI の引数もシェルの履歴に保存される場合があります。
• Node.js と npx をクライアントから利用できることを確認し、設定を変更した後はクライアントを再起動してください。
• 次のように試してください：「Webex を使って、自分のスペースを一覧表示してください。」 メッセージを検索するには、まずスペースを特定してください。webex_search_messages は一度に 1 つのスペースを検索します。

CLI オプション

オプション／コマンド	説明	デフォルト
--token	Webex アクセストークン（Bot モード）	$WEBEX_ACCESS_TOKEN
--fedramp	FedRAMP エンドポイントを使用	false
--debug	起動時のログを stderr に出力	false
login	OAuth ブラウザーログインを行い、トークンを保存	—
logout	保存済みの OAuth トークンを削除	—
auth-status	OAuth の有効期限メタデータを表示	—

ツール

スペース

ツール	説明
webex_list_spaces	認証済みユーザーのスペース（ルーム）を一覧表示
webex_search_spaces	タイトル／名前でスペースを検索（大文字と小文字を区別しない）
webex_get_space	ID でスペースの詳細を取得
webex_create_space	新しいスペースを作成
webex_update_space	スペースを更新
webex_delete_space	スペースを削除
webex_get_space_meeting_info	スペースの会議の詳細を取得

メッセージ

ツール	説明
webex_get_messages	スペース内のメッセージを一覧表示、または ID で 1 件を取得（includeFileDetails を指定すると、添付ファイルの名前／種類／サイズが追加されます）
webex_search_messages	1 つのスペース内でキーワード検索
webex_create_message	スペースまたは DM にテキストやファイルを添付して送信
webex_update_message	既存のメッセージを更新
webex_delete_message	メッセージを削除
webex_list_direct_messages	1 対 1 のダイレクトルーム内のメッセージを一覧表示（includeFileDetails は上記と同様）
webex_create_attachment_action	添付ファイルカードのアクションを送信
webex_get_attachment_action	添付ファイルアクションの詳細を取得

ファイル添付の送信

一般公開されている HTTP(S) URL の場合は、files を指定して webex_create_message を使用します。

{
  "roomId": "SPACE_ID",
  "text": "Here is the report",
  "files": ["https://example.com/report.pdf"]
}

ローカルファイルの場合は、代わりに filePath を使用してください。サーバーは multipart を使用してファイルの内容をアップロードします。ファイルは MCP サーバーを実行しているマシン上にあり、絶対パスで指定し、サイズは最大 100 MB である必要があります。

{
  "toPersonEmail": "[email protected]",
  "filePath": "/absolute/path/to/report.pdf"
}

Windows では、C:\\Reports\\report.pdf のような Windows の絶対パスを使用してください。ファイルを添付する場合、テキストと Markdown は省略できます。files は空であってはならず、filePath と同時に指定することはできません。宛先フィールド（roomId、toPersonId、toPersonEmail）と、スレッドへの返信で使う parentId は、テキストメッセージと同様に使用できます。URL のダウンロードと添付ファイルの制限は Webex によって適用されます。追加の認証情報が必要な非公開 URL は、公開ファイル URL として使用できません。Webex の添付ファイルガイドを参照してください。

ファイル

ツール	説明
webex_get_file_details	メッセージの files[] URL にあるファイルのメタデータ（ファイル名、種類、サイズ）を取得
webex_download_file	ファイルを読み込み（最大 10 MB）、画像はインライン表示、テキストは offset／maxChars でページ分割、ZIP／JAR はエントリー一覧として取得
webex_get_message_images	メッセージに添付されたすべての画像をダウンロードし、LLM のビジョン機能で使用
webex_save_file	1 つのファイルをローカルディスクに保存し、そのパスを返す（最大 100 MB）
webex_save_message_files	メッセージ内のすべてのファイルをローカルディスクに保存

受信した添付ファイルの読み取り

webex_download_file の戻り値は、ファイルの種類によって異なります。

ファイル	結果
PNG、JPEG、GIF、WebP	インラインの ImageContent
テキスト：text/*、JSON、XML、SQL、diff/patch、ソースコード	JSON の概要（totalChars、nextOffset、…）とテキスト。1 回の呼び出しあたりの maxChars（デフォルトは 50 000）
ZIP、JAR、WAR、EAR	エントリーの一覧（名前、サイズ、暗号化の有無）。展開はされません
その他すべて（PDF、docx、xlsx、…）	メタデータと webex_save_file の使用を促すヒント

PDF や Office ドキュメントの場合は、ファイルを保存してクライアント独自のツールで開いてください （多くのエージェントは PDF や画像を直接読み取れます。docx/xlsx にはスクリプトを使用してください）。保存先は <download dir>/<message-uuid>/<filename> です。ダウンロードディレクトリは WEBEX_DOWNLOAD_DIR または ~/.cache/webex-mcp/downloads です。ファイル名は Webex から取得し、デコードしてファイルシステムで安全な形式に変換されます。再度保存するとファイルは置き換えられ、同じメッセージ内で名前が重複するファイルには webex_save_message_files によって (1) が追加されます。本文は <name>.part にストリーミングされ、完了時にのみ名前が変更されます。保存したファイルは信頼できない入力として扱ってください。開くか一覧を表示するだけにし、実行してはいけません。

Webex がファイルのウイルススキャンを継続中の場合、423 Locked が返されます。ダウンロードは Retry-After に従って最大 10 秒待機し、失敗する前に 3 回再試行します。

メンバーシップ

ツール	説明
webex_list_memberships	スペースのメンバーシップを一覧表示
webex_get_membership	メンバーシップの詳細を取得
webex_add_membership	スペースにユーザーを招待
webex_update_membership	メンバーシップを更新（例：モデレーターに設定）
webex_remove_membership	スペースからユーザーを削除

ユーザー

ツール	説明
webex_get_people	メールアドレス、名前、または ID でユーザーを検索
webex_get_person	ID でユーザーを取得（自分自身には me を使用）

チーム

ツール	説明
webex_list_teams	チームを一覧表示
webex_create_team	チームを作成
webex_get_team	チームの詳細を取得
webex_update_team	チームを更新
webex_delete_team	チームを削除
webex_list_team_memberships	チームのメンバーシップを一覧表示
webex_add_team_membership	チームにユーザーを追加
webex_get_team_membership	チームメンバーシップの詳細を取得
webex_update_team_membership	チームメンバーシップを更新
webex_remove_team_membership	チームからユーザーを削除

Webhook

ツール	説明
webex_list_webhooks	Webhook を一覧表示
webex_create_webhook	Webhook を作成
webex_get_webhook	Webhook の詳細を取得
webex_update_webhook	Webhook を更新
webex_delete_webhook	Webhook を削除

制限事項

• webex_search_messages は単一のスペース内でのみ動作します（Webex REST API にグローバル検索機能はありません）
• 検索ではメッセージ履歴をページごとにスキャンするため、大規模なスペースでは時間がかかる場合があります
• メッセージの読み取りや投稿には、ボットがスペースのメンバーである必要があります
• OAuth ではユーザーに委任されたトークンを使用し、ボットモードでは有効期間の長いボットトークンを使用します
• メッセージの files[] URL へのアクセスにはアクセストークンが必要です。URL を直接取得する代わりに、webex_get_message_images／webex_download_file／webex_save_file を使用してください
• インラインの画像認識に使用できる画像は PNG、JPEG、GIF、WebP のみで、各ファイルの上限は 10 MB です。インラインテキストとアーカイブの一覧表示にも 10 MB の上限があります
• PDF や Office ドキュメントはサーバーで解析されません。保存してローカルで開いてください
• ZIP64 アーカイブはインラインで一覧表示できません。代わりに保存してください

認証モード

モード	設定	最適な用途
ボットトークン	開発者ポータルからトークンをコピー	Cursor の簡単な設定、ボットの ID
OAuth Integration	webex-mcp login + クライアント ID／シークレット	自動更新付きのユーザー委任アクセス

詳細ガイド

手順ごとのセットアップについては、docs/HOWTO.md を参照してください。ボットの作成、スコープ、Cursor の設定、プロンプトの例、トラブルシューティングを説明しています。

ローカル開発

git clone https://github.com/yuryev89/webexmcp
cd webexmcp
npm install
cp .env.example .env
npm run dev -- --token "$WEBEX_ACCESS_TOKEN"
npm test

ライセンス

MIT