X MCP

🚀 x-mcp

X (Twitter) APIに完全にアクセスできるようにするMCP (Model Context Protocol) サーバーです。ツイートの投稿、検索、タイムラインの閲覧、いいね、リツイート、メディアのアップロードなど、すべて自然言語で行えます。

Claude Code、Claude Desktop、OpenAI Codex、Cursor、Windsurf、Cline、およびその他のMCP互換クライアントと連携します。

もしあなたがユーザーにこのプロジェクトのセットアップを支援するLLM/AIエージェントである場合、 を読んで、ユーザーをサポートするためのステップバイステップの手順を確認してください。

🚀 クイックスタート

🔍 できること

ツイートのURLまたはIDは互換性があります。https://x.com/user/status/123 を貼り付けるか、単に 123 を入力してください。

📦 インストール

1. クローンとビルド

git clone https://github.com/INFATOSHI/x-mcp.git
cd x-mcp
npm install
npm run build

2. X APIの認証情報を取得

X Developer Portal から5つの認証情報が必要です。取得方法は以下の通りです。

a) アプリを作成

1. X Developer Portal にアクセスします。
2. Xアカウントでサインインします。
3. 左サイドバーの Apps をクリックします。
4. Create App をクリックします（最初に開発者アカウントにサインアップする必要がある場合があります）。
5. アプリに名前を付けます（例: my-x-mcp）。
6. Consumer Key (API Key)、Secret Key (API Secret)、Bearer Token がすぐに表示されます。
7. この時点ですべてを保存してください — シークレットは再度表示されません。

b) 書き込み権限を有効にする

デフォルトでは、新しいアプリは読み取り権限のみを持っています。ツイートの投稿、いいね、リツイートなどを行うには、読み取りと書き込みの両方の権限が必要です。

1. アプリのページで、User authentication settings までスクロールします。
2. Set up をクリックします。
3. App permissions を Read and write に設定します。
4. Type of App を Web App, Automated App or Bot に設定します。
5. Callback URI / Redirect URL を https://localhost に設定します（必須ですが、使用されません）。
6. Website URL を有効なURL（例: https://x.com）に設定します。
7. Save をクリックします。

c) アクセストークンを生成する（書き込み権限付き）

書き込み権限を有効にした後、新しい権限を持つアクセストークンとシークレットを生成（または再生成）する必要があります。

1. アプリの Keys and Tokens ページに戻ります。
2. Access Token and Secret の下で、Regenerate をクリックします。
3. Access Token と Access Token Secret の両方を保存します。

トークンを生成する前に手順 (b) をスキップすると、トークンは読み取り専用になり、投稿は403エラーで失敗します。

3. 認証情報を設定

サンプルの環境ファイルをコピーし、5つの認証情報を入力します。

cp .env.example .env

.env を編集します。

X_API_KEY=your_consumer_key
X_API_SECRET=your_secret_key
X_BEARER_TOKEN=your_bearer_token
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret

💻 クライアントとの接続

以下からクライアントを選択してください。1つのセクションの手順のみを実行すればOKです。

Claude Code

claude mcp add --scope user x-twitter -- node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

/ABSOLUTE/PATH/TO/x-mcp を実際にリポジトリをクローンしたパスに置き換えてください。その後、Claude Codeを再起動します。

Claude Desktop

以下の場所の claude_desktop_config.json に追加します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

Cursor

以下の場所のCursor MCP設定ファイルに追加します。

• グローバル (すべてのプロジェクト): ~/.cursor/mcp.json
• プロジェクトスコープ: プロジェクトのルートにある .cursor/mcp.json

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

Cursor Settings > MCP Servers で接続を確認することもできます。

OpenAI Codex

オプションA: CLI

codex mcp add x-twitter --env X_API_KEY=your_consumer_key --env X_API_SECRET=your_secret_key --env X_ACCESS_TOKEN=your_access_token --env X_ACCESS_TOKEN_SECRET=your_access_token_secret --env X_BEARER_TOKEN=your_bearer_token -- node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

オプションB: config.toml

~/.codex/config.toml（グローバル）または .codex/config.toml（プロジェクトスコープ）に追加します。

[mcp_servers.x-twitter]
command = "node"
args = ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"]

[mcp_servers.x-twitter.env]
X_API_KEY = "your_consumer_key"
X_API_SECRET = "your_secret_key"
X_ACCESS_TOKEN = "your_access_token"
X_ACCESS_TOKEN_SECRET = "your_access_token_secret"
X_BEARER_TOKEN = "your_bearer_token"

Windsurf

~/.codeium/windsurf/mcp_config.json に追加します。

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

Windsurf Settings > Cascade > MCP Servers からも追加できます。

Cline (VS Code)

ClineのMCP設定を開きます（Clineの上部ナビゲーションのMCP Serversアイコンをクリック > Configure）。そして、cline_mcp_settings.json に以下を追加します。

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

その他のMCPクライアント

これは標準のstdio MCPサーバーです。MCP互換のクライアントでは、以下を指定します。

node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

以下の環境変数を設定します: X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET, X_BEARER_TOKEN。

🛠️ トラブルシューティング

投稿時に403 "oauth1-permissions" エラーが発生する

アクセストークンは書き込み権限を有効にする前に生成されました。X Developer Portalにアクセスし、App permissionsが "Read and write" に設定されていることを確認してから、Regenerate をクリックしてアクセストークンとシークレットを再生成してください。

401 Unauthorized

.env 内の5つの認証情報がすべて正しく、余分なスペースや改行がないことを再度確認してください。

429 Rate Limited

エラーメッセージにはレート制限がリセットされる正確な時間が含まれています。その時間まで待つか、リクエスト頻度を減らしてください。

返信が権限/制限エラーで失敗する

2024年2月現在、XはAPIを介したプログラムによる返信を制限しています。元の投稿者があなたを @メンションするか、あなたの投稿を引用している場合にのみ返信できます。これはFree、Basic、Pro、Pay-Per-Useの各プランに適用されます（Enterpriseは除外）。quote_tweet を使って回避することができます。

サーバーが "Connected" と表示されるが、ツールが使用できない

正しいスコープ（ユーザー/グローバル、すべての場所で使用する場合はプロジェクトスコープではない）でサーバーを追加したことを確認し、クライアントを再起動してください。

📚 ドキュメント

レート制限

すべてのレスポンスにはレート制限の情報（残りのリクエスト数、総制限、リセット時間）が含まれています。制限に達すると、正確なリセットタイムスタンプが含まれた明確なエラーが返されます。

ページネーション

リストエンドポイントのレスポンスには next_token が含まれています。これを次のリクエストに渡すことで、次のページの結果を取得できます。これは search_tweets, get_timeline, get_mentions, get_followers, get_following で機能します。

検索クエリ構文

search_tweets ツールはXの完全なクエリ言語をサポートしています。

• from:username -- 特定のユーザーによる投稿
• to:username -- 特定のユーザーへの返信
• #hashtag -- ハッシュタグを含む投稿
• "exact phrase" -- 正確なテキスト一致
• has:media / has:links / has:images -- コンテンツタイプでフィルタリング
• is:reply / -is:retweet -- 投稿タイプでフィルタリング
• lang:en -- 言語でフィルタリング
• スペース (AND) または OR で組み合わせることができます。

📄 ライセンス

MIT