X (Twitter) Search MCP Server

MCP 対応クライアントから X (Twitter) の投稿をリアルタイム検索できる MCP サーバーです。2 つのデータ源 backend を選べます：

1. xAI backend — Responses API + x_search サーバーサイドツール。Grok が自律的に X を検索・分析（セマンティック検索）。

2. xurl backend — 公式 xurl CLI 経由の認証済み実 X API v2。生のポストデータを直接取得。

backend は環境変数 X_SEARCH_BACKEND で切り替えます（既定 auto）。

機能

Related MCP server: grok-mcp-server

backend の選択（X_SEARCH_BACKEND）

• xAI backend には XAI_API_KEY が必要です。

• xurl backend には xurl CLI が PATH 上にあり OAuth2 認証済み（xurl auth）であることが必要です。

• auto で xurl が利用できない環境では自動的に xAI にフォールバックするため、どちらか一方だけの構成でも動作します。

• x_get_trending は xurl に安定したトレンド API が無いため常に xAI backend を使用します。

対応クライアント

stdio トランスポートに対応した MCP クライアントであれば利用できます。代表的なものを以下に挙げます：

その他の MCP 対応クライアントは MCP Clients 一覧 を参照してください。

セットアップ

前提条件

• Python 3.10 以上

• xAI API キー（ https://console.x.ai/ から取得）— xAI backend を使う場合

• xurl CLI（ https://github.com/xdevplatform/xurl ）を導入し xurl auth で認証 — xurl backend を使う場合

いずれか一方だけでも動作します。両方を用意して X_SEARCH_BACKEND=auto（既定）にすると、xurl 優先・xAI フォールバックになります。

1. リポジトリのクローンと仮想環境の作成

git clone https://github.com/toocheap/x-search-mcp.git
cd x-search-mcp

# 仮想環境を作成
python3 -m venv .venv

# 仮想環境を有効化
# macOS / Linux:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

# 依存パッケージをインストール
pip install -r requirements.txt

2. 仮想環境の Python パスを確認

MCP クライアントの設定にはフルパスが必要です。以下のコマンドで確認してください：

# macOS / Linux（venv を有効化した状態で）
which python3
# 例: /Users/yourname/src/x-search-mcp/.venv/bin/python3

# Windows
# where python
# 例: C:\Users\yourname\src\x-search-mcp\.venv\Scripts\python.exe

3. MCP クライアントの設定

ほとんどの MCP クライアントは同じ JSON 形式の設定に対応しています。 以下の内容をお使いのクライアントの MCP 設定に追加してください：

{
    "mcpServers": {
        "x_search": {
            "command": "/absolute/path/to/x-search-mcp/.venv/bin/python3",
            "args": ["/absolute/path/to/x-search-mcp/x_search_mcp.py"],
            "env": {
                "XAI_API_KEY": "xai-xxxxxxxxxxxxxxxxxxxxxxxx",
                "X_SEARCH_BACKEND": "auto"
            }
        }
    }
}

重要:

• command には 手順2で確認した仮想環境の Python フルパスを指定してください。システムの python3 ではなく .venv 内のものを使います。

• args には x_search_mcp.py の絶対パスを指定してください。

• XAI_API_KEY には https://console.x.ai/ で取得した API キーを設定してください（xAI backend 用）。

• X_SEARCH_BACKEND は auto（既定）/ xurl / xai から選びます。省略時は auto。xurl backend は MCP サーバーを起動するユーザーの xurl 認証情報（~/.xurl）を使うため、env に資格情報を書く必要はありません。

4. クライアントを再起動

設定を保存したらクライアントを再起動してください。MCP サーバーが認識され、X 検索ツールが使えるようになります。

使用例

MCP クライアントで以下のように話しかけるだけです：

• 「AIに関する最新のツイートを検索して」

• 「@elonmusk の最近の投稿を見せて」

• 「日本でのトレンドを教えて」

• 「#cybersecurity のツイートを日本語で検索」

アーキテクチャ

                          ┌─ (xai)  xAI Responses API (/v1/responses) ─ x_search tool ─┐
MCP Client <-> MCP Server ┤                                                            ├─> X (Twitter) data
        (stdio)           └─ (xurl) xurl CLI ─ X API v2 (/2/tweets/search/recent 等) ──┘

• xAI backend: xAI の Responses API と x_search サーバーサイドツールを使用。Grok がサーバーサイドで自律的に X を検索・分析し、結果を返すエージェンティックな仕組みです。旧 Live Search API (search_parameters) は 2026年1月に廃止されたため、新しい Agent Tools API を使用しています。

• xurl backend: 公式 xurl CLI 経由で認証済みの X API v2 エンドポイント（/2/tweets/search/recent, /2/users/:id/tweets 等）を直接呼び出し、生のポストを取得します。アダプタは xurl_client.py に実装されています。

モデル

x_search サーバーサイドツールは grok-4 系モデルのみで利用可能です。

モデルを変更する場合は x_search_mcp.py 内の XAI_MODEL 定数を編集してください。

注意: grok-3 系モデルでは x_search ツールは利用できません（400 エラーになります）。

トラブルシューティング

x_auth_status ツールを呼ぶと、現在有効な backend と xurl の認証状態を確認できます。

Claude Desktop の場合、ログは以下で確認できます：

# macOS
cat ~/Library/Logs/Claude/mcp-server-x_search.log

料金

xAI API の利用料金が発生します。詳細は xAI Pricing を参照してください。

ライセンス

MIT