X API と開発者ドキュメント向けの MCP サーバー

AI ツールから X を扱うために、2 つの MCP(Model Context Protocol)サーバーが利用できます:

サーバー	できること	URL
X MCP	X API エンドポイントを呼び出す(ポスト検索、ユーザー検索、ブックマーク、トレンド、ニュース、Articles など)	`https://api.x.com/mcp`(ホスト型。`xurl mcp` 経由で接続)
Docs MCP	X API ドキュメントを検索・閲覧する	`https://docs.x.com/mcp`(ホスト型)

X MCP — X API

任意の MCP 対応 AI ツール(Grok Build、Cursor、Claude、VS Code、…)を X API に直接接続し、全アーカイブ検索、ユーザー検索、ブックマーク管理、トレンドやニュースの取得、Articles の下書きまで、あなたの X アカウントの権限で実行できます。 X API は https://api.x.com/mcp で Streamable HTTP 形式のホスト型 MCP サーバー(プロトコル 2025-06-18、serverInfo: xmcp)を公開しています。これにはオープンソースの xurl mcp ブリッジ経由でアクセスします。ブリッジが OAuth を処理し、呼び出しごとに最新の Bearer トークンを差し込みます。

機能の概要

カテゴリ	モデルが実行できること
Posts	ポストの取得、いいねした人/リポストした人/引用した人の取得、直近のカウント
Search	全アーカイブのポスト検索、ユーザー検索、ニュース検索
Users	現在のユーザーの解決、id/ハンドルからの検索、ユーザーのポスト、タイムライン、メンションの読み取り
Bookmarks	ブックマークの一覧/追加/削除、ブックマークフォルダの管理
News & Trends	ニュース記事の取得、ロケーション(WOEID)のトレンドの取得
Articles	Articles の下書き作成と公開

仕組み

X の OAuth では あなた自身の 開発者アプリが必要です(動的クライアント登録はなく、api.x.com/mcp はネイティブの MCP OAuth ディスカバリを公開していません)。そのため、クライアントを URL に直接向ける代わりに、小さなローカルブリッジを実行します。このブリッジはアプリの ID を保持し、一度きりのログインを実行して、トークンを最新の状態に保ちます。

ブリッジは npm ランチャー(npx)経由で動作するため、個別のインストール手順は不要です。
キャッシュされたトークンがない初回実行時には、ブラウザを開いて 1 回限りの OAuth2 ログインを行い、その後はトークンをキャッシュして 自動的に更新 し続けます。
すべての診断情報は stderr に出力され、stdout は JSON-RPC 専用のクリーンなチャネル に保たれます。

はじめに

2 つのルートのいずれかを選択します:

シンプル — App-only Bearer。 アプリの Bearer トークンを MCP クライアントの Authorization ヘッダーに貼り付けます。ブリッジもブラウザログインも不要です。読み取り専用のエンドポイントで、ユーザーコンテキストはありません(あなたとしての操作はできません)。カスタムヘッダー付きのリモート MCP に対応するクライアントで動作します。
フル — xurl mcp ブリッジ(OAuth 2.0 ユーザーコンテキスト)。 ローカルブリッジが OAuth 2.0 PKCE ログインを処理し、トークンを自動更新するため、モデルはあなたのアカウントのスコープで動作します。書き込み(ブックマーク、Articles)やユーザーコンテキストを使うツールには必須です。

シンプルルート(app-only Bearer)

X 開発者ポータルで X アプリを作成 します。
アプリの “Keys and tokens” ページから App-only Bearer トークンをコピー します。
クライアントを https://api.x.com/mcp に向け、トークンを Authorization ヘッダーとして設定します — 後述の App-only(URL に直接、ブリッジなし) のスニペットを参照してください。

フルルート(xurl ブリッジ)

OAuth 2.0 を有効にした X アプリを作成 します。
アプリにリダイレクト URI http://localhost:8080/callback を登録します(初回のブラウザログインに必要)。別のものを使う場合は、REDIRECT_URI を設定し、そちらを登録してください。
CLIENT_ID と CLIENT_SECRET をコピー します — これらをクライアント設定に記述します。xurl auth oauth2 を手動で実行する場合(下記のヘッドレスフローなど)は、事前にそのシェルで環境変数としてエクスポートしておいてください — 設定しないままだとブラウザでのログインが失敗します。
Node.js がインストール済み であること(npx 用)。

xurl のインストール を推奨します:

brew install --cask xdevplatform/tap/xurl      # Homebrew
npm install -g @xdevplatform/xurl              # npm (global)
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

初回ログインにはブラウザが必要です。 ヘッドレス/リモートマシンでは、まず xurl auth oauth2 --headless でアウトオブバンド認証(コード貼り付け方式)を行ってください。その後はブリッジがキャッシュ済みトークンを再利用します。ヘッドレスを参照。

クライアントを接続する

1. Grok Build

[mcp_servers.xapi]
command = "npx"
args = ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]
enabled = true
startup_timeout_sec = 300          # give the first-run browser login time

[mcp_servers.xapi.env]
CLIENT_ID = "YOUR_X_APP_CLIENT_ID"
CLIENT_SECRET = "YOUR_X_APP_CLIENT_SECRET"

または、1 つのコマンドで xurl ブリッジを追加します(-e フラグはサーバーの環境変数になり、-- 以降の引数は npx に渡されます):

grok mcp add xapi npx \
  -e CLIENT_ID=YOUR_X_APP_CLIENT_ID \
  -e CLIENT_SECRET=YOUR_X_APP_CLIENT_SECRET \
  -- -y @xdevplatform/xurl mcp https://api.x.com/mcp

確認と一覧表示:

grok mcp doctor xapi      # ✓ server started, ✓ handshake OK, ✓ tools discovered
grok mcp list

初めてツールを呼び出したとき(または doctor 実行時)に X のログインのためにブラウザが開きます — 一度完了すれば設定は完了です。

2. Cursor

~/.cursor/mcp.json(グローバル、すべてのプロジェクト)または .cursor/mcp.json(このプロジェクトのみ)を作成します:

{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": {
        "CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
      }
    }
  }
}

次に Cursor → Settings → MCP を開き、xapi が緑のドットとツールを表示していることを確認します。初回使用時に Cursor がブリッジを起動し、ブラウザがログイン用に開きます。ハンドシェイクが完了するとツール一覧が表示されます。

3. Claude Desktop

claude_desktop_config.json を編集します(macOS: ~/Library/Application Support/Claude/、Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": { "CLIENT_ID": "YOUR_X_APP_CLIENT_ID", "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET" }
    }
  }
}

Claude Desktop を再起動すると、ツール(🔌)メニューに X のツールが表示されます。

4. VS Code(GitHub Copilot / Agent モード)

.vscode/mcp.json に追加します:

{
  "servers": {
    "xapi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": { "CLIENT_ID": "YOUR_X_APP_CLIENT_ID", "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET" }
    }
  }
}

5. 任意の MCP クライアント

xurl ブリッジ(stdio):

フィールド	値
`command`	`npx`
`args`	`["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]`
`env`	`CLIENT_ID`, `CLIENT_SECRET`
起動タイムアウト	300 秒以上(初回ログインが完了できるように)

xurl をネイティブにインストール済みの場合は、command/args を "command": "xurl", "args": ["mcp", "https://api.x.com/mcp"] に置き換えてください。 App-only Bearer(リモート HTTP):

フィールド	値
`url`	`https://api.x.com/mcp`
`headers.Authorization`	`Bearer YOUR_APP_ONLY_BEARER_TOKEN`

認証

OAuth 2.0 ユーザーコンテキスト(デフォルト)

ブリッジは あなた自身として 認証(PKCE フロー)するため、ツールはあなたのアカウントのスコープで動作します。資格情報の解決順序は: CLIENT_ID/CLIENT_SECRET 環境変数 → ~/.xurl のアクティブなアプリ。トークンは ~/.xurl にキャッシュされ、自動的に更新されます(401 の後の強制更新を含む)。

初回のブラウザログイン

キャッシュされたトークンがない場合、ブリッジは stderr に出力してブラウザを開きます:

[xurl mcp] no valid OAuth2 token; opening the browser to sign in -- complete the login to start the bridge...
[xurl mcp] authentication complete; starting bridge

MCP のハンドシェイクは完了するまで保留されます — これがクライアントに余裕のある startup_timeout_sec が必要な理由です。

ヘッドレス / リモートマシン

ブラウザが利用できない場合は、一度アウトオブバンドで認証してからクライアントを起動します:

# 必須: クライアント設定の env ブロックはブリッジにのみ適用され、
# 手動の xurl 実行には適用されません — このシェルで先に認証情報をエクスポートしてください。
export CLIENT_ID="YOUR_X_APP_CLIENT_ID"
export CLIENT_SECRET="YOUR_X_APP_CLIENT_SECRET"

xurl auth oauth2 --headless                 # prints an auth URL; you paste back the redirect URL/code
xurl auth oauth2 --app my-app --headless    # for a specific app

App-only(URL に直接、ブリッジなし)

読み取り系のエンドポイントについては、ブリッジを省略し、静的な App-only Bearer トークン を使ってクライアントを URL に直接向けることもできます。カスタムヘッダーをサポートするリモート MCP 対応クライアントに便利です:

# ~/.grok/config.toml
[mcp_servers.xapi_direct]
url = "https://api.x.com/mcp"
enabled = true

[mcp_servers.xapi_direct.headers]
Authorization = "Bearer YOUR_APP_ONLY_BEARER_TOKEN"

トレードオフ: 自動更新がなく、ユーザーコンテキストもありません(あなたとしてのアクションは実行できません)。フル機能を使うにはブリッジを推奨します。

複数のアプリとアカウント

OAuth ログインでは、ブラウザを開いたときにログインしている X アカウント が認可されます — 必ずしもアプリの所有アカウントとは限りません。サブアカウントや Bot アカウントとしてポストしたい場合は、ログインを完了する前にブラウザ側でそのアカウントに切り替えてください(あるいは、以前に認可済みのユーザーを選ぶために -u を使ってください)。

xurl --app my-app mcp                  # bridge using a specific registered app
xurl mcp -u alice https://api.x.com/mcp  # act as a specific OAuth2 user

クライアント設定では、args に "--app", "my-app" または "-u", "alice" を追加します。

設定リファレンス

設定	場所	注記
`CLIENT_ID` / `CLIENT_SECRET`	`env`	X アプリの資格情報(または `~/.xurl` に登録されたアプリを使用)
`REDIRECT_URI`	`env`	コールバックを上書きします。アプリに登録されている必要があります。デフォルトは `http://localhost:8080/callback`
`startup_timeout_sec`	クライアント設定	初回ログインを完了できるよう 300 以上に設定
`[URL]` 位置引数	`args`	デフォルトは `https://api.x.com/mcp`
`--app NAME`	`args`	特定の登録済みアプリを使用
`-u, --username`	`args`	特定の OAuth2 ユーザーとして動作

高度な環境変数の上書き(通常は不要): AUTH_URL、TOKEN_URL、API_BASE_URL、INFO_URL。

検証とトラブルシューティング

grok mcp doctor xapi          # Grok Build: end-to-end check
# or test the bridge by hand (Ctrl-C to exit):
npx -y @xdevplatform/xurl mcp https://api.x.com/mcp

症状	原因と対処
クライアントが起動時にタイムアウトする	`startup_timeout_sec` を 300 以上に上げる。ブリッジはブラウザログインを待っています
ブラウザが開かない	ディスプレイがない(ヘッドレス) → まず `xurl auth oauth2 --headless` を実行。`npx` が解決できることを確認
`401` / `token refresh failed`	アプリの資格情報が誤っているか、リフレッシュトークンが失効 → ログインを再実行(`xurl auth oauth2 [--app NAME]`)
ブラウザに “Something went wrong — You weren’t able to give access to the App” と表示される	`xurl` の実行環境で `CLIENT_ID`/`CLIENT_SECRET` が設定されていない → クライアントの `env` ブロックに記述するか、`xurl auth oauth2` を手動で実行する前にシェルで `export` してください
ブラウザでリダイレクト/コールバックエラー	`http://localhost:8080/callback` がアプリに登録されていない(または `REDIRECT_URI` が不一致)
ログイン後に `client-not-enrolled`	アプリが適切な X パッケージ/環境にない → ポータルで Pay-per-use + Production に移動
`npx` が古いバージョンを取得する	プライベートレジストリミラーがデフォルトになっている → `args` に `--registry=https://registry.npmjs.org/` を固定する
出力が空または文字化けする	クライアントを `--verbose` で実行しないこと。stdout は JSON-RPC 専用のクリーンなチャネルである必要があります

セキュリティとベストプラクティス

~/.xurl とアクセストークンはシークレットとして扱ってください — チャット、ログ、共有設定に貼り付けないでください。生のシークレットをコミットするよりも、環境変数を参照するプロジェクト単位の .mcp.json/.grok/config.toml の利用を推奨します。
MCP には 専用のアプリ を使用し、必要なスコープのみを付与してください。
書き込みはレート制限の対象 です(ブックマーク、article_publish)。読み取りより厳しく、時折 429 が発生することを想定してバックオフしてください。
ブリッジはローカルで動作します — 認証情報がマシンを離れることはなく、Bearer トークンとして TLS 経由で api.x.com に送信されるだけです。

Docs MCP — ドキュメント検索

X API ドキュメント用の MCP サーバーが https://docs.x.com/mcp でホストされています。AI ツールに接続することで、ワークフローを離れることなくドキュメントページを検索・閲覧できます。

利用可能なツール

ツール	説明
`search_x`	X ドキュメント全体から関連情報、コード例、API リファレンス、ガイドを検索
`get_page_x`	パスを指定してドキュメントページの完全なコンテンツを取得

設定

ドキュメント MCP サーバーを MCP クライアントの設定に追加します:

{
  "mcpServers": {
    "x-docs": {
      "url": "https://docs.x.com/mcp"
    }
  }
}

X API で開発している際に、AI アシスタントにエンドポイントの詳細、認証ガイド、コード例をその場で参照させたい場合に便利です。

両方のサーバーを併用する

両方の MCP サーバーを同時に接続できます。これにより、AI アシスタントはドキュメントの参照と API の呼び出しの両方を行えるようになります。 Grok Build(~/.grok/config.toml):

[mcp_servers.xapi]
command = "npx"
args = ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"]
enabled = true
startup_timeout_sec = 300

[mcp_servers.xapi.env]
CLIENT_ID = "YOUR_X_APP_CLIENT_ID"
CLIENT_SECRET = "YOUR_X_APP_CLIENT_SECRET"

[mcp_servers.x-docs]
url = "https://docs.x.com/mcp"
enabled = true

Cursor / Claude 系(mcp.json):

{
  "mcpServers": {
    "xapi": {
      "command": "npx",
      "args": ["-y", "@xdevplatform/xurl", "mcp", "https://api.x.com/mcp"],
      "env": {
        "CLIENT_ID": "YOUR_X_APP_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_X_APP_CLIENT_SECRET"
      }
    },
    "x-docs": {
      "url": "https://docs.x.com/mcp"
    }
  }
}

OpenAPI 仕様

X API v2 のすべてのエンドポイントに対する機械可読な API 仕様です。

リソース	URL
OpenAPI Spec (JSON)	`https://api.x.com/2/openapi.json`

curl https://api.x.com/2/openapi.json -o openapi.json

API クライアントの自動生成、Postman へのインポート、カスタム AI エージェントへの組み込み、リクエスト/レスポンススキーマの検証などに利用できます。

​X MCP — X API

​機能の概要

​仕組み

​はじめに

​シンプルルート(app-only Bearer)

​フルルート(xurl ブリッジ)

​クライアントを接続する

​1. Grok Build

​2. Cursor

​3. Claude Desktop

​4. VS Code(GitHub Copilot / Agent モード)

​5. 任意の MCP クライアント

​認証

​OAuth 2.0 ユーザーコンテキスト(デフォルト)

​初回のブラウザログイン

​ヘッドレス / リモートマシン

​App-only(URL に直接、ブリッジなし)

​複数のアプリとアカウント

​設定リファレンス

​検証とトラブルシューティング

​セキュリティとベストプラクティス

​Docs MCP — ドキュメント検索

​利用可能なツール

​設定

​両方のサーバーを併用する

​OpenAPI 仕様

X MCP — X API

機能の概要

仕組み

はじめに

シンプルルート(app-only Bearer)

フルルート(xurl ブリッジ)

クライアントを接続する

1. Grok Build

2. Cursor

3. Claude Desktop

4. VS Code(GitHub Copilot / Agent モード)

5. 任意の MCP クライアント

認証

OAuth 2.0 ユーザーコンテキスト(デフォルト)

初回のブラウザログイン

ヘッドレス / リモートマシン

App-only(URL に直接、ブリッジなし)

複数のアプリとアカウント

設定リファレンス

検証とトラブルシューティング

セキュリティとベストプラクティス

Docs MCP — ドキュメント検索

利用可能なツール

設定

両方のサーバーを併用する

OpenAPI 仕様