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）。

機能

ツール名	機能
x_search_posts	キーワード・ハッシュタグ・トピックで X の投稿を検索
x_get_user_posts	特定ユーザーの最近の投稿を取得
x_get_trending	トレンドトピックを取得（常に xAI backend を使用）
x_auth_status	有効な backend と xurl 認証状態を確認

backend の選択（X_SEARCH_BACKEND）

値	挙動
auto（既定）	xurl が認証済みなら xurl を使用、未認証 / 失敗時は xAI にフォールバック
xurl	xurl CLI を強制（実 X API v2）
xai	xAI Responses API を強制

• 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 クライアントであれば利用できます。代表的なものを以下に挙げます：

クライアント	種類
Claude Desktop	デスクトップアプリ
Claude Code	CLI
Cursor	コードエディタ
Windsurf	コードエディタ
VS Code (GitHub Copilot)	コードエディタ
Cline	VS Code 拡張
Roo Code	VS Code 拡張
Cherry Studio	デスクトップアプリ
5ire	デスクトップアプリ

その他の 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 に資格情報を書く必要はありません。

<details> <summary>クライアント別の設定ファイルの場所</summary>

クライアント	設定ファイル
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	~/.claude/settings.json または claude mcp add コマンド
Cursor	Settings → MCP → Add Server
Windsurf	Settings → Advanced Settings → Cascade
VS Code (Copilot)	Settings → MCP → Edit in settings.json

</details>

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 系モデルのみで利用可能です。

モデル	特徴
grok-4-1-fast	ツール呼び出し最適化・高速（デフォルト）
grok-4-1-fast-reasoning	推論付き・より高精度

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

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

トラブルシューティング

エラー	原因	対処
Failed to spawn process: No such file or directory	Python パスが間違っている	.venv/bin/python3 のフルパスを command に指定
status 400: model not supported	grok-3 系モデルを使用	XAI_MODEL を grok-4-1-fast に変更（デフォルトで設定済み）
status 401	API キーが無効	XAI_API_KEY を確認
status 410: Live search is deprecated	旧 API を使用	最新版に更新（git pull）
{"error": "xurl is not authenticated...", "source": "xurl"}	X_SEARCH_BACKEND=xurl だが xurl 未認証	xurl auth で認証する、または X_SEARCH_BACKEND=xai に変更
{"error": "...HTTP 429...", "source": "xurl"}	xurl のレート制限	時間をおいて再試行（429 は内部でバックオフ再試行済み）

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

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

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

料金

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

ライセンス

MIT