TwittrAPI

twittrapi-mcp – Claude、Cursor、その他の AI エージェント向け Twitter/X MCP サーバー

TwittrAPI 向けの MCP サーバーです。TwittrAPI は、ツイート、プロフィール、フォロワー、検索、リスト、コミュニティなど、Twitter/X の公開データを扱う REST API です。Claude、Cursor、その他の MCP クライアントから、1,000 回あたり 0.065 ドルから、X の開発者アカウントなしでデータを読み取れます。

API キーを取得： twittrapi.com/start · 料金 · ドキュメント · ステータス · RapidAPI でも利用可能です

SDK とインテグレーション： Python · Node.js · Go · n8n · Make · Apify · LangChain · LlamaIndex · エージェントスキル · 使用例

X Corp. とは提携していません。

ホスト型サーバー（インストール不要）

リモート MCP サーバーに対応したアプリは、URL で接続できます（ホスト型リリースで利用可能です。twittrapi.com/docs/hosted-mcp をご覧ください）。

https://mcp.twittrapi.com/mcp

クライアント	設定
Claude.ai / Claude Desktop	Settings > Connectors > Add custom connector を開き、URL を貼り付けて Connect をクリックし、TwittrAPI にログインしてアクセスを許可します（OAuth）
ChatGPT	Settings > Apps & Connectors > Advanced settings > Developer mode を開き、Create with the URL と OAuth を選択します
Claude Code	claude mcp add --transport http twittrapi https://mcp.twittrapi.com/mcp（OAuth）、または --header "Authorization: Bearer $TWITTRAPI_API_KEY" を追加します
Cursor	mcp.json に {"mcpServers": {"twittrapi": {"url": "https://mcp.twittrapi.com/mcp", "headers": {"X-API-KEY": "${env:TWITTRAPI_API_KEY}"}}}} を記述します
VS Code	.vscode/mcp.json に {"servers": {"twittrapi": {"type": "http", "url": "https://mcp.twittrapi.com/mcp"}}} を記述します（OAuth）

OAuth を使う場合、アプリが API キーを参照することはありません。ほかの API 呼び出しと同様に、利用料金は残高から差し引かれます。接続済みアプリはダッシュボードの Connected apps に一覧表示され、接続を解除することもできます。

必要なもの

• Node.js 20 以降
• TwittrAPI キー、または Twitter AIO API に登録済みの RapidAPI キー

ツールを呼び出すたびに、アカウントに API 呼び出し 1 回分の料金が発生します。

インストール

Claude Code

claude mcp add twittrapi --env TWITTRAPI_API_KEY=your-key -- npx -y twittrapi-mcp

Claude Desktop

Settings > Developer > Edit Config を開き、claude_desktop_config.json に次の内容を追加します。

{
  "mcpServers": {
    "twittrapi": {
      "command": "npx",
      "args": ["-y", "twittrapi-mcp"],
      "env": {
        "TWITTRAPI_API_KEY": "your-key"
      }
    }
  }
}

その後、Claude Desktop を再起動します。

Cursor

すべてのプロジェクトで使う場合は ~/.cursor/mcp.json に、特定のプロジェクトで使う場合は .cursor/mcp.json に次の内容を追加します。

{
  "mcpServers": {
    "twittrapi": {
      "command": "npx",
      "args": ["-y", "twittrapi-mcp"],
      "env": {
        "TWITTRAPI_API_KEY": "your-key"
      }
    }
  }
}

その他のクライアント

stdio サーバーを起動できるクライアントであれば利用できます。コマンドは npx -y twittrapi-mcp です。

環境変数

変数	必須	説明
TWITTRAPI_API_KEY	2つのキーのいずれか	TwittrAPI キーです。X-API-KEY ヘッダーとして送信されます。
RAPIDAPI_KEY	2つのキーのいずれか	RapidAPI キーです。TWITTRAPI_API_KEY が設定されていない場合にのみ使用されます。
RAPIDAPI_HOST	いいえ	RapidAPI のリスティングのホストです。デフォルトは twitter-aio.p.rapidapi.com です。
TWITTRAPI_BASE_URL	いいえ	直接 API のベース URL です。デフォルトは https://api.twittrapi.com です。
TWITTRAPI_RESPONSE_FORMAT	いいえ	simple（デフォルト）または raw です。レスポンス形式を参照してください。
TWITTRAPI_X_COOKIE	いいえ	ログイン済みのご自身の x.com セッションの Cookie です。TWITTRAPI_X_PROXY とともに設定すると、アカウントツールが有効になります。
TWITTRAPI_X_PROXY	いいえ	アカウントツール用のプロキシです。http://user:pass@host:port の形式で指定します。
TWITTRAPI_X_CHAT_PASSCODE	いいえ	X Chat のパスコードです。send_dm と、list_dm_conversations のメッセージテキストが追加されます。

どちらのキーも設定されていない場合でも、サーバーは起動してツールを一覧表示しますが、すべての呼び出しでキーの設定方法を説明するエラーが返されます。

代わりに RapidAPI を使用する

RapidAPI 経由でアクセスを購入した場合は、TWITTRAPI_API_KEY の代わりに RAPIDAPI_KEY を設定します。

"env": { "RAPIDAPI_KEY": "your-rapidapi-key" }

リクエストは x-rapidapi-key ヘッダーと x-rapidapi-host ヘッダーを付けて、https://twitter-aio.p.rapidapi.com に送信されます。ツールとその出力は同じです。

RapidAPI の別の TwittrAPI リスティングを購読していますか？そのホストを設定してください。 "RAPIDAPI_HOST": "twttr.p.rapidapi.com"。

ツール

これらのツールは公開データを読み取り、常に利用できます。X セッションを設定すると、アカウントツールが追加されます。

ツール	機能
get_user_by_username	ハンドル名からプロフィールを取得します。数値のユーザー ID も含みます
get_user_by_id	数値のユーザー ID からプロフィールを取得します
username_to_id	ハンドル名からユーザー ID を特定します
users_by_ids	最大 500 件のユーザー ID のプロフィールを一度に取得します
get_user_tweets	ユーザーのツイート
get_user_tweets_and_replies	ユーザーのツイートと返信
get_user_media	写真または動画を含むユーザーのツイート
get_followers	ユーザーのフォロワー
get_following	ユーザーがフォローしているアカウント
get_verified_followers	ユーザーの認証済みフォロワー
get_user_affiliates	組織と提携しているアカウント
get_friendships_batch	あるアカウントが最大 50 件の他のアカウントをフォローしているか、またその逆も確認します
get_user_about_batch	最大 20 件のハンドル名について「このアカウントについて」を取得します
search_tweets	X の演算子で検索します。トップ、最新、ユーザー、写真、動画に対応します
get_tweet	ツイートとその返信スレッド
tweets_by_ids	最大 100 件のツイートを ID で一度に取得します
get_tweet_retweets	ツイートをリツイートしたユーザー
get_tweet_quotes	ツイートを引用しているツイート
get_tweet_replies	ツイートへの返信のみ
get_tweet_thread	ツイートを含む、投稿者自身のスレッド
get_list_details	リスト名、所有者、件数
get_list_tweets	リストのメンバーによるツイート
get_list_members	リストのメンバー
get_community	コミュニティの詳細
get_community_about	コミュニティの「概要」ページ：ルール、モデレーター、メンバー
get_community_tweets	コミュニティ内のツイート
search_communities	キーワードでコミュニティを検索します
get_trends	場所（WOEID）ごとのトレンドトピック
get_trend_locations	トレンドがある場所とその WOEID
get_space	X Space：タイトル、状態、ホスト、参加者

ユーザーのタイムラインツール（get_user_tweets、get_followers など）では、userId または username のいずれかを指定できます。バッチツールはハンドル名ごとに 1 回分の呼び出しとして課金されます。tweets_by_ids は ID の数にかかわらず 1 回分の呼び出しです。

アカウントツール

TWITTRAPI_X_COOKIE と TWITTRAPI_X_PROXY を設定すると、サーバーには自分の X アカウントを操作するツールも表示されます。

ツール	機能
create_tweet	ツイートを投稿します。引用（quoteUrl）、投票（pollChoices）、返信制限は任意です
reply_to_tweet	ツイートに返信します
delete_tweet	自分のツイートを削除します
like_tweet, unlike_tweet	ツイートに「いいね」する、または取り消します
retweet, unretweet	リツイートする、または取り消します
bookmark_tweet, unbookmark_tweet	ブックマークを追加または削除します
follow_user, unfollow_user	フォローする、または解除します（userId または username を指定）
list_dm_conversations	自分の DM 受信箱を表示します
send_dm	ダイレクトメッセージを送信します（TWITTRAPI_X_CHAT_PASSCODE が必要です）
create_list	リストを作成します
add_list_member, remove_list_member	リストメンバーを追加または削除します
create_draft, list_drafts	下書きを保存する、自分の下書き一覧を表示します
list_bookmark_folders, list_bookmark_folder_tweets	自分のブックマークフォルダーと、その中のツイートを表示します（X Premium）
search_bookmarks	自分のブックマークを検索します
list_community_memberships	自分が参加しているコミュニティを表示します
list_articles, get_article	自分の X Articles（下書きまたは公開済み）の一覧と、1 件の記事を表示します（X Premium）
create_article, update_article	新しい記事を下書きとして保存する、または記事を変更します（X Premium）
publish_article, unpublish_article, delete_article	記事を公開する、公開を取り消す、または削除します（X Premium）

Cookie の取得方法とプロキシの設定方法については、twittrapi.com/docs/x-session をご覧ください。 Cookie には auth_token と ct0 が必要です。ダイレクトメッセージには twid も必要です。

"env": {
  "TWITTRAPI_API_KEY": "your-key",
  "TWITTRAPI_X_COOKIE": "auth_token=...; ct0=...; twid=u%3D...",
  "TWITTRAPI_X_PROXY": "http://user:pass@host:port"
}

• Cookie とプロキシはサーバーの設定に保存されます。ツールの引数ではないため、モデルに渡されることはなく、ログに記録されたり、結果として返されたりすることもありません。
• 書き込みツールには readOnlyHint: false が設定されています（削除と取り消し操作には destructiveHint: true も設定されています）。そのため、クライアントは実行前に確認を求めます。
• 各呼び出しは、読み取りツールと同様に、課金対象の API 呼び出し 1 回として扱われます。
• アカウントツールは stdio 経由でのみ利用できます。HTTP モードとホスト型サーバーでは利用できません。

レスポンス形式

ツールの結果では、既定で API のシンプル形式が使用されます。これは、固定スキーマを持つフラットな camelCase JSON です（リストの場合は {"data": [...], "nextCursor": ..., "hasNextPage": ...}、単一オブジェクトの場合は {"data": {...}}）。ツイートには id、url、text、createdAt、author、counts、media、quoted、retweetOf などのフィールドが含まれます。ユーザーには username、name、description、counts などが含まれます。X の生の GraphQL JSON と比べて、トークン数は約 60％少なくなります。

代わりに生の JSON を取得するには（カード、投票、編集履歴、コミュニティノートなど、シンプル形式で省略されるフィールドを取得する場合）：

• 呼び出しごとに指定する場合：ツールでは任意の format 引数に "simple" または "raw" を指定できます。
• サーバー全体に設定する場合：TWITTRAPI_RESPONSE_FORMAT=raw を設定します（format 引数が優先されます）。

一部のエンドポイントにはシンプル形式がありません。get_space、get_community_about、バッチツール、新しいアカウントツール（ブックマークフォルダーと検索、コミュニティ、記事）が該当します。これらのツールには format 引数がなく、常に生の JSON を返します。

出力サイズとページネーション

生のレスポンスは数百 KB になることがあります。すべてのツールでは任意の max_chars 引数を指定できます（既定値は 50,000、範囲は 1,000～1,000,000 です）。出力がこれを超えると途中で切り詰められ、末尾に [TRUNCATED ...] マーカーが付加されます。

ページネーションを行うツールでは、JSON の上にカーソルが表示されるため、出力が切り詰められてもカーソルは失われません。

next_cursor: DAABCgABGZ...
Pass next_cursor as `cursor` to get the next page.

{"data":{...}}

最終ページでは、ヘッダーに next_cursor: none (last page, no more results) と表示されます。シンプル形式では、hasNextPage が false の場合がこれに該当します。生の形式では、レスポンスに次のカーソルがない場合（「いいね」のタイムラインが空の場合も含む）、X が送信したカーソルと同じカーソルを返した場合、またはページにカーソルのみが含まれ、結果がない場合に該当します。

エラー

API エラーは、次のような簡単な説明を添えたツールエラーとして返されます。

• 402：アカウントの残高がありません
• 429：レート制限に達しました。再試行する前にお待ちください
• 404：ユーザーまたはツイートが存在しないか、非公開、または停止されています
• 5xx：一時的な上流の問題です

HTTP モード（リモートホスティング）

npx -y twittrapi-mcp --http --port 3333 --host 0.0.0.0

これは、/mcp にステートレスなストリーミング可能 HTTP エンドポイントを、/health にヘルスチェックを提供します。デフォルトのホストは 127.0.0.1 です。各 POST で、呼び出し元の認証情報に紐づいたサーバーインスタンスが個別に作成されるため、スティッキーセッションなしで、ロードバランサーの背後で任意の数のインスタンスを実行できます。GET /mcp は 405 を返します（サーバー起動ストリームには対応していません）。従来の SSE トランスポートは提供されません。

HTTP モードでは、サーバーは自身の環境変数に設定されたキーを使用しません。各リクエストに呼び出し元の認証情報を含めます。

• 直接 API では X-API-KEY: <key> または Authorization: Bearer <key>
• RapidAPI では x-rapidapi-key: <key>。twitter-aio.p.rapidapi.com 以外のリスティングでは、さらに x-rapidapi-host: <host> が必要です（.p.rapidapi.com で終わる必要があります）
• Authorization: Bearer twa_at_...：TwittrAPI OAuth アクセストークン（下記のホステッドモード）

アカウントツールは HTTP モードでは提供されません。また、TWITTRAPI_X_COOKIE と TWITTRAPI_X_PROXY は無視されます。TWITTRAPI_BASE_URL と TWITTRAPI_RESPONSE_FORMAT は引き続き環境から読み込まれます。呼び出し元は format 引数で呼び出しごとに形式を指定できます。インターネットからアクセス可能な場合は、サーバーを HTTPS の背後に配置してください。

独自のインスタンス向けのクライアント設定例（Claude Code）：

claude mcp add --transport http twittrapi https://your-host.example.com/mcp --header "X-API-KEY: your-key"

OAuth を使用するホステッドモード

OAuth が必要なクライアント（Claude.ai コネクター、ChatGPT）向けに、サーバーは OAuth 2.1 リソースサーバーとして、TwittrAPI ダッシュボードは認可サーバーとして動作します（動的クライアント登録、PKCE S256、同意画面、ローテーションするリフレッシュトークン）。サーバーは次の処理を行います。

• 認証情報なしのリクエストに 401 と WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="mcp" を返します。
• /.well-known/oauth-protected-resource/mcp と /.well-known/oauth-protected-resource で RFC 9728 のメタデータを提供し、ダッシュボードの RFC 8414 メタデータを /.well-known/oauth-authorization-server で中継します。
• ダッシュボードの内部イントロスペクションエンドポイント（共有シークレット）で各アクセストークンを検証します。有効な結果は最大 OAUTH_CACHE_SECONDS（30）秒間、無効な結果は 5 秒間キャッシュし、オーディエンスが MCP_PUBLIC_URL のトークンのみを受け入れます。
• トークンに紐づくアカウントのキーで API を呼び出します。キーがクライアントに渡ることはありません。無効または取り消し済みのトークンには、error="invalid_token" を付けて 401 を返します。ダッシュボードに接続できない場合は Retry-After を付けて 503 を返すため、クライアントはトークンを保持します。

環境（HTTP モード）

変数	デフォルト	説明
PORT, HOST	3333, 127.0.0.1	リッスンアドレス（Docker イメージでは 3000、0.0.0.0 を使用します）
TWITTRAPI_BASE_URL	https://api.twittrapi.com	ツールが呼び出すゲートウェイ
TWITTRAPI_RESPONSE_FORMAT	simple	ツールの結果のデフォルト形式
MCP_PUBLIC_URL	–	/mcp の公開 URL。例：https://mcp.twittrapi.com/mcp。トークンの対象者です。
OAUTH_ISSUER	–	認可サーバー。例：https://app.twittrapi.com
OAUTH_INTROSPECTION_SECRET	–	ダッシュボードとの共有シークレット（32 文字以上）。これら 3 つを設定すると OAuth が有効になります。
OAUTH_INTROSPECTION_URL	$OAUTH_ISSUER/api/oauth/introspect	イントロスペクションエンドポイントの内部 URL
OAUTH_METADATA_URL	$OAUTH_ISSUER/.well-known/oauth-authorization-server	中継されるメタデータの取得先
OAUTH_CACHE_SECONDS	30	有効なトークンのキャッシュ期間（最大 300 秒）。この時間内に失効が反映されます。
MAX_CONCURRENCY_PER_KEY	8	キーおよびインスタンスごとの処理中リクエスト数。上限を超えると Retry-After: 1 を付けて 429 を返します。0 にすると無効になります。
MAX_BODY_BYTES	262144	リクエスト本文がこれを超えると 413 を返します
REQUEST_TIMEOUT_MS	90000	リクエストの実行時間がこれを超えると 504 を返します
ALLOWED_ORIGINS	–	ブラウザーのクライアント向けの、カンマ区切りの Origin 許可リスト（DNS リバインディング対策）
TRUST_PROXY	–	1 にすると、X-Forwarded-For からクライアント IP を取得してログに記録します
LOG_LEVEL	info	debug、info、warn、error

ログは標準出力に JSON 行形式で出力され、リクエストごとに 1 行記録されます。内容は、リクエスト ID、クライアント IP、認証の種類（api_key、rapidapi、oauth、none）、ハッシュ化されたキー ID（k_ + 12 桁の 16 進数）、OAuth クライアントとアカウント ID、JSON-RPC メソッド、ツール名、ステータス、処理時間です。キーとトークンはログに記録されません。

Docker / Coolify

docker build -t twittrapi-mcp .
docker run -p 3000:3000 -e MCP_PUBLIC_URL=... -e OAUTH_ISSUER=... -e OAUTH_INTROSPECTION_SECRET=... twittrapi-mcp

Coolify では、ビルドパックに Dockerfile、ポートに 3000、ヘルスチェックパスに /health、ドメインに mcp.twittrapi.com を指定し、上記の変数を設定します。同じサーバー上で両方を実行する場合は、 OAUTH_INTROSPECTION_URL にダッシュボードの内部アドレスを設定してください。

開発

npm install
npm run build
npm test

npm test は最初にビルドを行い、その後、単体テスト、stdio と HTTP でサーバーを起動しローカルのモック API に対して実行するプロトコルテスト、さらに偽のダッシュボードを使ったホストモードのテスト（OAuth チャレンジとメタデータ、トークンのイントロスペクションとキャッシュ、対象者のチェック、制限、ログの機密情報削除）を実行します。

ツールを追加または変更するには、src/endpoints.ts を編集してください。各エントリーには、名前、説明、API パス、zod のパラメータースキーマがあります。各ツールには max_chars と、エントリーで rawOnly が設定されていない場合は format も指定されます。エントリーでは simplify 関数を設定して、解析済みの JSON をさらに整形することもできますが、現在そのようなエントリーはありません。アカウント関連のツールは src/actions.ts にあります。

MCP Inspector を使ってサーバーを対話的に試すには、次のコマンドを実行します。

npx @modelcontextprotocol/inspector -e TWITTRAPI_API_KEY=your-key node dist/index.js

サポート

質問、不具合、またはより高いレート制限については、[email protected] にメールするか、このリポジトリで Issue を作成してください。サービスの状態：twittrapi.com/status。ニュースと変更情報：TwittrAPI Telegram チャンネル（リンクはウェブサイトにあります）。

ライセンス

MIT