🐦 技術調査 - xmcp

概要

xmcp は、X（旧 Twitter）の公式 OpenAPI 仕様を FastMCP 経由で MCP（Model Context Protocol）ツールとして公開するローカルサーバーです。xdevplatform（X 社の開発者プラットフォーム公式アカウント）が公開し、LLM クライアント（Claude、Grok など）から X API を直接呼び出すための橋渡しを担います。

ユーザーは python server.py を起動するだけで、X API の約 110 種類のエンドポイントが MCP ツールとして自動登録され、http://127.0.0.1:8000/mcp 経由で利用できます。ストリーミング系と Webhook 系のエンドポイントは、MCP の同期リクエスト/レスポンスモデルに適さないため除外されます。

類似プロジェクトとの位置づけは次のとおりです。

本記事は前者（xdevplatform/xmcp）を調査対象とします。

特徴

• OpenAPI 駆動。X API v2 の openapi.json を起動時に取得し、operation を 1:1 で MCP ツールへ変換します。API の更新に追従しやすい設計です。
• ストリーミング除外。/stream・/webhooks を含むパスや x-twitter-streaming: true 属性を持つ operation は自動で除外されます。
• ツールフィルタリング。環境変数 X_API_TOOL_ALLOWLIST、X_API_TOOL_DENYLIST、X_API_TOOL_TAGS で、起動時にツール一覧を絞り込めます。
• OAuth1 ブラウザフロー。起動時に自動でブラウザを開き、ローカル HTTP サーバー（既定ポート 8976）で callback を受けてアクセストークンを取得します。
• トークンのメモリ保持。OAuth1 アクセストークンはサーバープロセスのライフタイム中のみメモリに保持し、ディスクに永続化しません。
• httpx event_hooks による署名注入。すべての X API リクエストは sign_oauth1_request フックで OAuth1 署名ヘッダーを付与します。
• クエリパラメータ正規化。OpenAPI 上で explode: false かつ type: array のクエリパラメータを、カンマ区切り文字列へ自動結合します。
• デバッグ支援。X_API_DEBUG、X_OAUTH_PRINT_TOKENS、X_OAUTH_PRINT_AUTH_HEADER でリクエスト、トークン、署名ヘッダーを出力できます。
• Grok テストクライアント同梱。test_grok_mcp.py で、xAI Grok から MCP 経由で X API を呼ぶ動作確認ができます。

構造

システムコンテキスト図

コンテナ図

コンポーネント図

データ

概念モデル

情報モデル

構築方法

前提条件

• Python 3.9 以上
• X Developer Platform のアプリ登録（Consumer Key/Secret、Bearer Token の発行）
• OAuth1 ユーザーコンテキスト利用時はブラウザが使える環境
• オプションで xAI API キー（Grok テストクライアント用）

依存パッケージ

requirements.txt に定義する依存は次のとおりです。

インストール手順

git clone https://github.com/xdevplatform/xmcp.git
cd xmcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

環境変数の設定

env.example を .env にコピーして必須項目を記入します。

cp env.example .env

必須変数は次のとおりです。

OAuth1 callback 用の既定値は次のとおりです。通常は変更不要です。

X_OAUTH_CALLBACK_HOST=127.0.0.1
X_OAUTH_CALLBACK_PORT=8976
X_OAUTH_CALLBACK_PATH=/oauth/callback
X_OAUTH_CALLBACK_TIMEOUT=300

X Developer App へのコールバック登録

X Developer Portal のアプリ設定画面で、次の URL を Callback URI に登録します。

http://127.0.0.1:8976/oauth/callback

起動

python server.py

起動時にブラウザが開き、OAuth1 の同意画面が表示されます。承認するとローカルの callback サーバーがトークンを受け取り、FastMCP が OpenAPI spec を読み込んでツール一覧を標準出力に表示します。

MCP エンドポイントは既定で http://127.0.0.1:8000/mcp です。

利用方法

必須パラメータの扱い

X API の多くの operation は、tweet.fields や user.fields などの field selector パラメータを必須とします。xmcp ではこれらは OpenAPI spec 定義どおりに MCP ツールの入力スキーマへ露出するため、MCP クライアント側で明示的に指定する必要があります。

MCP クライアントからの接続

• ローカルクライアント（Claude Desktop など）。http://127.0.0.1:8000/mcp を直接指定
• リモートクライアント（Grok など）。ngrok で公開してから公開 URL を指定

ngrok http 8000
# 出力された https://<id>.ngrok-free.dev/mcp を MCP_SERVER_URL に設定

ツールのホワイトリスト

X_API_TOOL_ALLOWLIST にカンマ区切りで operationId を指定します。

X_API_TOOL_ALLOWLIST=getUsersByUsername,createPosts,searchPostsRecent

設定変更後はサーバーを再起動してください。フィルターは起動時の 1 回だけ評価されます。

代表的なツール呼び出し例

全リスト（約 110 件）は README の "Available tool calls" を参照してください。

OAuth2 ユーザートークンの生成

1. .env に CLIENT_ID と CLIENT_SECRET を追加します
2. generate_authtoken.py の redirect_uri をアプリ設定と一致させます
3. python generate_authtoken.py を実行し、出力されたトークンを X_OAUTH_ACCESS_TOKEN に設定します

Grok テストクライアントの実行

export XAI_API_KEY=xai-xxxxx
export MCP_SERVER_URL=http://127.0.0.1:8000/mcp
python test_grok_mcp.py

運用

起動と停止

server.py はフォアグラウンド実行を想定しています。停止は Ctrl+C です。常駐化する場合は systemd、launchd、supervisord、tmux、screen などと組み合わせます。

状態確認

MCP エンドポイントが応答するかは次のコマンドで確認できます。

curl -i http://127.0.0.1:8000/mcp

ログ確認

X_API_DEBUG=1（既定値）でリクエスト/レスポンスの INFO ログが出力されます。

INFO xmcp.x_api: X API request GET https://api.x.com/2/users/me
INFO xmcp.x_api: X API response GET https://api.x.com/2/users/me -> 200

4xx/5xx 応答時は x-transaction-id ヘッダーとレスポンス本文（最大 1000 バイト）を WARNING で記録します。X サポートへの問い合わせ時はこの transaction-id を添付します。

トークン更新

OAuth1 アクセストークンは、プロセスのライフタイム限定でメモリ保持されます。サーバーを再起動するたびにブラウザ同意フローが再実行されます。長時間稼働では、事前に取得したトークンを X_OAUTH_ACCESS_TOKEN と X_OAUTH_ACCESS_TOKEN_SECRET に設定しておくことで同意フローをスキップできます。

レート制限

X API のレート制限は HTTP 429 として返却されます。xmcp は再試行を行わないため、MCP クライアント側か上位アプリケーションで指数バックオフを実装してください。応答ヘッダーの x-rate-limit-remaining と x-rate-limit-reset を監視します。

スケール

単一プロセス、単一ユーザーでの利用を前提とした設計です。複数ユーザーで共有する場合は、ユーザーごとに別プロセスを起動するか、前段にリバースプロキシと認証レイヤーを置く設計が必要です。

ベストプラクティス

最小権限のツールセット

本番投入時は X_API_TOOL_ALLOWLIST で必要最小限のツールだけを公開してください。全 110 ツールを無制限に公開すると、LLM が意図せず deletePosts や unfollowUser などの破壊的操作を選択するリスクがあります。

秘密情報の管理

• .env は .gitignore に必ず含めます
• 本番では OS の secret manager（AWS Secrets Manager、HashiCorp Vault など）から環境変数として注入します
• X_OAUTH_PRINT_TOKENS=1 と X_OAUTH_PRINT_AUTH_HEADER=1 は開発時のみ使用し、本番では無効化します

ローカル境界の維持

既定の MCP_HOST=127.0.0.1 を維持し、外部公開が必要な場合でも直接 0.0.0.0 バインドは避けてください。ngrok や Cloudflare Tunnel 越しに公開し、トンネル側で認証を掛けます。

OpenAPI 更新への追従

X API の OpenAPI spec は予告なく更新されます。新 operation の登場やパラメータ変更に追従するため、定期的にサーバーを再起動してください。allowlist に含まれた operationId が spec から消えた場合、起動時の tool list 出力で検知できます。

CI/CD での dry-run

CI でツール一覧の差分を監視するには、print_tool_list の出力をスナップショットとして比較します。想定外のツールの増減を検出できます。

トラブルシューティング

ログの読み解き

• xmcp.x_api ロガー。API リクエスト/レスポンス
• xmcp.oauth1 ロガー。コールバックサーバーの受信ログ
• X_OAUTH_PRINT_AUTH_HEADER=1 で OAuth1 署名ヘッダーを stdout に出力し、手動で X API を再現できます

まとめ

xmcp は、X API v2 の OpenAPI 仕様を FastMCP 経由で MCP ツール化する、X 社公式のローカルサーバーです。起動するだけで約 110 種類のツールが自動登録され、allowlist による最小権限化と OAuth1 ブラウザフローによる安全なユーザーコンテキスト呼び出しが実現できます。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNS でのシェアをいただけると励みになります！

引用文献

• 公式ドキュメント
  • X API Documentation
  • X Developer Portal
  • X API OpenAPI Spec
  • FastMCP Documentation
  • Model Context Protocol 公式
  • httpx Documentation
  • requests-oauthlib
  • xAI Grok API
• GitHub
  • xdevplatform/xmcp
  • jlowin/fastmcp
  • basementstudio/xmcp
  • modelcontextprotocol/typescript-sdk