X (Twitter) MCP server

X（Twitter）MCP サーバー

AI ツールを介して Twitter（X）とやり取りするための Model Context Protocol（MCP）サーバーです。このサーバーでは、AI ツールでの自然言語コマンドを通じて、ツイートの取得や投稿、Twitter の検索、フォロワーの管理などを行えます。

特徴

• ユーザープロフィール、フォロワー、フォロー中のユーザー一覧を取得できます。
• ツイートの投稿、削除、お気に入り登録ができます。
• Twitter でツイートやトレンドを検索できます。
• ブックマークやタイムラインを管理できます。
• Twitter API のレート制限に標準で対応しています。
• 適切な認証（API キーとトークン）を使用する Twitter API v2 を利用し、アカウント停止のリスクを最小限に抑えるため、ユーザー名とパスワードを使う方法は使用しません。
• ユーザー管理、ツイート管理、タイムライン、検索機能に関する Twitter API v2 のエンドポイントを完全に実装しています。

前提条件

• Python 3.10 以降：Python がシステムにインストールされていることを確認してください。
• Twitter Developer Account：Twitter Developer Portalで API 認証情報（API Key、API Secret、Access Token、Access Token Secret、Bearer Token）を取得する必要があります。
• 任意：Claude Desktop：Anthropic のウェブサイトから Claude Desktop アプリをダウンロードしてインストールします。
• 任意：Node.js（MCP 連携用）：Claude Desktop で MCP サーバーを実行するために必要です。
• Python の依存関係を管理するための uv や pip などのパッケージマネージャー。

インストール

オプション 1：Smithery 経由でインストール（推奨）

Smitheryを介して、Claude Desktop 用の X（Twitter）MCP サーバーを自動的にインストールするには：

npx -y @smithery/cli install @rafaljanicki/x-twitter-mcp-server --client claude

オプション 2：PyPI からインストール

x-twitter-mcp をインストールする最も簡単な方法は、PyPI を利用することです。

pip install x-twitter-mcp

オプション 3：ソースからインストール

ソースリポジトリからインストールする場合：

1. リポジトリをクローンする：

   git clone https://github.com/rafaljanicki/x-twitter-mcp-server.git
   cd x-twitter-mcp-server
   

2. 仮想環境をセットアップする（任意ですが、推奨）：

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. 依存関係をインストールする： uv を使用する場合（プロジェクトでは uv.lock を使用するため推奨）：

   uv sync
   

   または、pip を使用する場合：

   pip install .
   

4. 環境変数を設定する：

   • プロジェクトのルートに .env ファイルを作成します（用意されている場合は .env.example をコピーできます）。
   • Twitter API の認証情報を追加します：

     TWITTER_API_KEY=your_api_key
     TWITTER_API_SECRET=your_api_secret
     TWITTER_ACCESS_TOKEN=your_access_token
     TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret
     TWITTER_BEARER_TOKEN=your_bearer_token
     

   • ブックマークツール（get_bookmarks、delete_all_bookmarks）を使用するには、OAuth 2.0 ユーザーアクセストークンも追加します：

     TWITTER_OAUTH2_USER_ACCESS_TOKEN=your_oauth2_user_token
     

     下記のOAuth 2.0 ユーザートークンの取得を参照してください。

OAuth 2.0 ユーザートークンの取得

ブックマークのエンドポイント（GET /2/users/:id/bookmarks、DELETE /2/users/:id/bookmarks/:tweet_id）ではOAuth 2.0 User Contextが必要です。アプリ専用のベアラートークンと OAuth 1.0a はどちらも拒否されます。ユーザーにスコープを限定したトークンを取得するには、PKCE 認証フローを一度実行する必要があります。

手順

1. Twitter Developer Portalでアプリを開き、Settings → User authentication settingsに進んで OAuth 2.0 を有効にします。コールバック URL（例：https://localhost/）を設定してください。

2. Tweepy を使って PKCE フローを実行します：

import tweepy

handler = tweepy.OAuth2UserHandler(
    client_id="YOUR_CLIENT_ID",       # OAuth 2.0 Client ID (from Developer Portal)
    redirect_uri="https://localhost/",
    scope=["bookmark.read", "bookmark.write", "users.read", "offline.access"],
    client_secret="YOUR_CLIENT_SECRET",  # Optional for public clients
)

print(handler.get_authorization_url())
# Open the URL, authorize, copy the redirected URL, then:
redirected_url = input("Paste redirected URL: ")
token = handler.fetch_token(redirected_url)
print(token["access_token"])

3. 取得したトークンを、環境変数または .env ファイルの TWITTER_OAUTH2_USER_ACCESS_TOKEN に設定します。

サーバーの実行

推奨されるトランスポートは Streamable HTTP です。次のいずれかを使用してください。

推奨：Streamable HTTP（Docker/Smithery）

Streamable HTTP と SSE エンドポイントを使用して、サーバーを HTTP サービスとして実行します。

1. Docker イメージをビルドします：

   docker build -t x-twitter-mcp .
   

2. コンテナを実行します（Smithery では PORT を使用します。ここでのデフォルトは 8081 です）：

   docker run -p 8081:8081 -e PORT=8081 x-twitter-mcp
   

3. エンドポイント：

   • Streamable HTTP（HTTP 経由の JSON-RPC）：POST http://localhost:8081/mcp
   • SSE（Server-Sent Events）：GET http://localhost:8081/sse

4. リクエストごとに、base64 でエンコードした config クエリパラメーターを使用して設定を渡します（Smithery ではこの方法を推奨します）。設定 JSON の例：

   {"twitterApiKey":"...","twitterApiSecret":"...","twitterAccessToken":"...","twitterAccessTokenSecret":"...","twitterBearerToken":"..."}
   

   エンコードして initialize を呼び出します：

   CONFIG_B64=$(printf '%s' '{"twitterApiKey":"YOUR_KEY","twitterApiSecret":"YOUR_SECRET","twitterAccessToken":"YOUR_TOKEN","twitterAccessTokenSecret":"YOUR_TOKEN_SECRET","twitterBearerToken":"YOUR_BEARER"}' | base64)
   
   curl -sS -X POST "http://localhost:8081/mcp?config=${CONFIG_B64}" \
     -H 'content-type: application/json' \
     -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"capabilities":{}}}'
   

注意：

• POST / は 404 を返します。Streamable HTTP には /mcp、SSE には /sse を使用してください。
• Smithery 経由でデプロイする場合、smithery.yaml は runtime: container および startCommand.type: http を使用するように設定されています。

Streamable HTTP（ローカル、Docker 不使用）

ASGI サーバーを直接実行します。

PyPI からインストールした場合：

python -m x_twitter_mcp.http_server

ソースから uv を使用してインストールした場合：

uv run python -m x_twitter_mcp.http_server

エンドポイントと設定の渡し方は上記と同じです。

レガシー STDIO（CLI スクリプト）

このプロジェクトでは、STDIO を必要とするデスクトップクライアント向けに、STDIO CLI スクリプト x-twitter-mcp-server も提供しています。

PyPI からインストールした場合：

x-twitter-mcp-server

ソースから uv を使用してインストールした場合：

uv run x-twitter-mcp-server

Claude Desktop での使用

この MCP サーバーを Claude Desktop で使用するには、サーバーに接続するよう Claude を設定する必要があります。次の手順に従ってください。

手順 1：Node.js をインストールする

Claude Desktop は MCP サーバーの実行に Node.js を使用します。Node.js がインストールされていない場合：

• nodejs.org から Node.js をダウンロードしてインストールします。
• インストールを確認します：

  node --version
  

手順 2：Claude Desktop の設定ファイルを見つける

Claude Desktop は MCP サーバーの設定に claude_desktop_config.json ファイルを使用します。

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

ファイルが存在しない場合は、作成してください。

手順 3：MCP サーバーを設定する

claude_desktop_config.json を編集し、x-twitter-mcp サーバーを追加します。/path/to/x-twitter-mcp-server は、実際のプロジェクトディレクトリのパス（ソースからインストールした場合）または Python 実行ファイルのパス（PyPI からインストールした場合）に置き換えてください。

PyPI からインストールした場合：

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "x-twitter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "TWITTER_BEARER_TOKEN": "your_bearer_token",
        "TWITTER_OAUTH2_USER_ACCESS_TOKEN": "your_oauth2_user_token"
      }
    }
  }
}

ソースから uv を使用してインストールした場合：

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-twitter-mcp-server",
        "run",
        "x-twitter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

• "command": "x-twitter-mcp-server"：PyPI からインストールした場合、CLI スクリプトを直接使用します。
• "env"：PyPI からインストールした場合、設定ファイルに環境変数を直接指定する必要がある場合があります（.env ファイルがないためです）。ソースからインストールした場合は、.env ファイルが使用されます。
• "env": {"PYTHONUNBUFFERED": "1"}：Claude でのログ記録を改善するため、出力がバッファリングされないようにします。

手順 4：Claude Desktop を再起動する

• Claude Desktop を完全に終了します。
• Claude Desktop を再度開き、新しい設定を読み込みます。

手順 5：接続を確認する

• Claude Desktop を開きます。
• 入力エリアの右下隅にハンマーまたはコネクターのアイコンが表示されていることを確認します。これは MCP ツールが使用可能であることを示します。
• アイコンをクリックすると、post_tweet、search_twitter、get_user_profile など、x-twitter-mcp が提供するツールを確認できます。

手順 6：Claude でテストする

Claude Desktop で自然言語を使って Twitter を操作できるようになりました。プロンプトの例を以下に示します。

• ユーザープロフィールを取得する：

  Get the Twitter profile for user ID 123456.
  

  Claude は get_user_profile ツールを呼び出し、ユーザーの詳細を返します。

• ツイートを投稿する：

  Post a tweet saying "Hello from Claude Desktop! #MCP"
  

  Claude は post_tweet ツールを使用してツイートを投稿し、その操作を確認します。

• Twitter を検索する：

  Search Twitter for recent tweets about AI.
  

  Claude は search_twitter ツールを呼び出し、関連するツイートを返します。

• トレンドを取得する：

  What are the current trending topics on Twitter?
  

  Claude は get_trends ツールを使用して、トレンドのトピックを取得します。

プロンプトが表示されたら、そのチャットセッションで MCP ツールを使用する権限を Claude に付与してください。

OpenClaw 連携ワークフロー

MCP クライアントから Twitter API v2 ツールを直接呼び出す場合、この MCP サーバーが最適です。ワークフローが OpenClaw で実行され、プラグインのインストールメタデータ、エンドポイントの検出、監視アラート、Webhook、抽選、メディアのアップロードまたはダウンロードのワークフロー、ダイレクトメッセージ、フォロワーのエクスポート、または承認を必要とする投稿や返信の操作が必要な場合は、TweetClaw を別の OpenClaw プラグインとして使用し、確認済みのツイート ID または URL をツール間で渡してください。

認証情報を分離し、書き込み操作の重複を防ぐコマンドフローについては、OpenClaw 連携ワークフローを参照してください。

利用可能なツール

以下は、x-twitter-mcp サーバーが提供するすべてのツールと、自然言語のプロンプトを使って Claude Desktop で実行する例の一覧です。

ユーザー管理ツール

get_user_profile

• 説明：ユーザーのプロフィールの詳細情報を取得します。
• Claude Desktop の例：

  Get the Twitter profile for user ID 123456789.
  

  Claude は、ID、名前、ユーザー名、プロフィール画像の URL、自己紹介を含むユーザーのプロフィール詳細を返します。

get_user_by_screen_name

• 説明：スクリーンネームでユーザーを取得します。
• Claude Desktop の例：

  Get the Twitter user with screen name "example_user".
  

  Claude はユーザーのプロフィール詳細を返します。

get_user_by_id

• 説明：ID でユーザーを取得します。
• Claude Desktop の例：

  Fetch the Twitter user with ID 987654321.
  

  Claude はユーザーのプロフィール詳細を返します。

get_user_followers

• 説明：指定したユーザーのフォロワー一覧を取得します。
• Claude Desktop の例：

  Get the followers of user ID 123456789, limit to 50.
  

  Claude は最大 50 人のフォロワー一覧を返します。

get_user_following

• 説明：指定したユーザーがフォローしているユーザーを取得します。
• Claude Desktop の例：

  Who is user ID 123456789 following? Limit to 50 users.
  

  Claude は最大 50 人のユーザー一覧を返します。

get_user_followers_you_know

• 説明：共通のフォロワー一覧を取得します。
• Claude Desktop の例：

  Get common followers for user ID 123456789, limit to 50.
  

  Claude は最大 50 人の共通フォロワー一覧を返します（フォロワーを絞り込んでシミュレートします）。

get_user_subscriptions

• 説明：指定したユーザーがサブスクリプション登録しているユーザーの一覧を取得します。
• Claude Desktop の例：

  Get the subscriptions for user ID 123456789, limit to 50.
  

  Claude は最大 50 人のユーザー一覧を返します（サブスクリプションの代わりにフォローを使用します）。

ツイート管理ツール

post_tweet

• 説明：メディア、返信、タグを任意で指定してツイートを投稿します。
• Claude Desktop の例：

  Post a tweet saying "Hello from Claude Desktop! #MCP"
  

  Claude はツイートを投稿し、その詳細を返します。

delete_tweet

• 説明：ID でツイートを削除します。
• Claude Desktop の例：

  Delete the tweet with ID 123456789012345678.
  

  Claude はツイートを削除し、操作が完了したことを確認します。

get_tweet_details

• 説明：特定のツイートの詳細情報を取得します。
• Claude Desktop の例：

  Get details for tweet ID 123456789012345678.
  

  Claude は ID、本文、作成日、投稿者 ID を含むツイートの詳細を返します。

create_poll_tweet

• 説明：投票付きのツイートを作成します。
• Claude Desktop の例：

  Create a poll tweet with the question "What's your favorite color?" and options "Red", "Blue", "Green" for 60 minutes.
  

  Claude は投票付きツイートを作成し、その詳細を返します。

vote_on_poll

• 説明：投票に回答します。
• Claude Desktop の例：

  Vote "Blue" on the poll in tweet ID 123456789012345678.
  

  Claude はモックの応答を返します（Twitter API v2 は投票に対応していないため）。

favorite_tweet

• 説明：ツイートを「いいね」します。
• Claude Desktop の例：

  Like the tweet with ID 123456789012345678.
  

  Claude はツイートに「いいね」し、操作が完了したことを確認します。

unfavorite_tweet

• 説明：ツイートの「いいね」を取り消します。
• Claude Desktop の例：

  Unlike the tweet with ID 123456789012345678.
  

  Claude はツイートの「いいね」を取り消し、操作が完了したことを確認します。

bookmark_tweet

• 説明：ツイートをブックマークに追加します。
• Claude Desktop の例：

  Bookmark the tweet with ID 123456789012345678.
  

  Claude はツイートをブックマークし、操作が完了したことを確認します。

delete_bookmark

• 説明：ツイートをブックマークから削除します。
• Claude Desktop の例：

  Remove the bookmark for tweet ID 123456789012345678.
  

  Claude はブックマークを削除し、操作が完了したことを確認します。

delete_all_bookmarks

• 説明：破壊的で、元に戻せません。すべてのページを取得してブックマークを1つずつ削除し、すべてのブックマークを完全に削除します。TWITTER_OAUTH2_USER_ACCESS_TOKEN が必要です。
• Claude Desktop の例：

  Delete all my Twitter bookmarks.
  

  Claude はまずユーザーに確認してから、すべてのブックマークを削除し、件数を報告します。

get_bookmarks

• 説明：認証済みユーザーのブックマークしたツイートを取得します。1回の呼び出しで最大100件のツイートを返します。ページネーションには cursor パラメーターを使用します。TWITTER_OAUTH2_USER_ACCESS_TOKEN が必要です。
• Claude Desktop の例：

  Show my Twitter bookmarks, limit to 25.
  

  Claude は、ID、テキスト、作成日、投稿者 ID を含む、最大25件のブックマークしたツイートを返します。

タイムラインと検索のツール

get_timeline

• 説明：ホームタイムライン（おすすめ）からツイートを取得します。
• Claude Desktop の例：

  Show my Twitter For You timeline, limit to 20 tweets.
  

  Claude は、おすすめタイムラインから最大20件のツイートを返します。

get_latest_timeline

• 説明：ホームタイムライン（フォロー中）からツイートを取得します。
• Claude Desktop の例：

  Show my Twitter Following timeline, limit to 20 tweets.
  

  Claude は、フォロー中のタイムラインから最大20件のツイートを返します。

search_twitter

• 説明：クエリを指定して Twitter を検索します。
• Claude Desktop の例：

  Search Twitter for recent tweets about AI, limit to 10.
  

  Claude は、AI に関する最近のツイートを最大10件返します。

get_trends

• 説明：Twitter のトレンドトピックを取得します。
• Claude Desktop の例：

  What are the current trending topics on Twitter? Limit to 10.
  

  Claude は、トレンドトピックを最大10件返します。

get_highlights_tweets

• 説明：ユーザーのタイムラインからハイライトされたツイートを取得します。
• Claude Desktop の例：

  Get highlighted tweets from user ID 123456789, limit to 20.
  

  Claude は、ユーザーのタイムラインから最大20件のツイートを返します（ハイライトを模擬）。

get_user_mentions

• 説明：特定のユーザーに言及しているツイートを取得します。
• Claude Desktop の例：

  Get tweets mentioning user ID 123456789, limit to 20.
  

  Claude は、そのユーザーに言及しているツイートを最大20件返します。

トラブルシューティング

• サーバーが起動しない場合：

  • .env ファイルに必要な Twitter API の認証情報がすべて設定されていることを確認してください（ソースからインストールした場合）。
  • PyPI からインストールした場合は、claude_desktop_config.json またはシェルに環境変数が設定されていることを確認してください。
  • x-twitter-mcp-server の実行時にエラーがないか、ターミナルの出力を確認してください。
  • uv または Python の実行ファイルが正しくインストールされ、アクセス可能であることを確認してください。

• Claude がサーバーを検出しない場合：

  • claude_desktop_config.json のパスが正しいことを確認してください。
  • command と args が正しい実行ファイルとスクリプトを指していることを確認してください。
  • 設定ファイルを更新した後、Claude Desktop を再起動してください。
  • Claude の開発者モードのログ（ヘルプ → 開発者モードを有効にする → MCP ログファイルを開く）でエラーを確認してください。

• レート制限エラー：

  • サーバーにはレート制限への対応が含まれていますが、Twitter API の制限に達した場合は、リセット時間（ツイート操作では15分など）まで待つ必要があります。

• ブックマークのツールが 403 を返す場合：

  • get_bookmarks と delete_all_bookmarks には TWITTER_OAUTH2_USER_ACCESS_TOKEN が必要です。アプリ専用のベアラートークンと OAuth 1.0a は、ブックマークのエンドポイントでは拒否されます。
  • 設定方法については、OAuth 2.0 ユーザートークンの取得を参照してください。

• 構文警告：

  • Tweepy から SyntaxWarning メッセージが表示される場合、Python 3.13 での Tweepy の docstring の問題が原因です。サーバーには、これに対処するための警告抑制が含まれています。

コントリビューション

コントリビューションを歓迎します！GitHub リポジトリで issue を作成するか、プルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。

作者

• Rafal Janicki - [email protected]