Twitter/X MCP

Twitter/X MCP

Twitter/X MCP を使うと、MCP クライアントから X の公開投稿、返信、プロフィールを読み込んだり、X を検索したりできます。デフォルトでは Rettiwt を使用するため、X の開発者向けプランは不要です。アクセス権があれば、公式 X API に切り替えることもできます。

要件

• サポート対象として指定されているランタイムは、Node 22 リリース系列の Node.js 22.21.0 以降です。Node 24 のテスト結果とインストール時の制限については、以下をご覧ください。
• RETTIWT_API_KEY が必要です。API モードを選択した場合は、公式 X API の認証情報を使用できます。

Node 24 との互換性

Node.js 24.19.0 で、プロジェクト全体のチェックと、MCP ツールを実際に呼び出す 5 つすべてのテストに合格しました。CI でも Node 24 でプロジェクト全体のチェックを実行します。

公開済みのパッケージと Rettiwt 7.1.4 は、引き続き engines.node: "^22.21.0" を指定しています。そのため、Node 24 でインストールすると EBADENGINE 警告が表示されることがあり、engine-strict が有効な場合は npm がインストールを拒否します。指定されているサポート範囲内でインストールするには、Node 22.21.0 またはそれ以降の Node 22 リリースを使用してください。Rettiwt が Node 24 との互換性を宣言するリリースを公開し、それに合わせてこのパッケージのエンジン範囲が更新されるまでは、公式の Node 24 サポートは保留中です。

クイックスタート

パッケージが公開されたら、MCP クライアントからクローンなしで実行できます。

npx -y @granitebps/twitter-mcp

TWITTER_MODE を省略すると、サーバーは Rettiwt を選択します。クライアントの設定で RETTIWT_API_KEY を渡してください。

サーバーは stdio を使用します。標準出力は MCP の通信専用にしてください。

クローンしたリポジトリから実行する

サーバーを開発する場合、またはクローンを直接使用する場合：

git clone https://github.com/granitebps/twitter-mcp.git
cd twitter-mcp
npm ci
npm run build

コンパイル済みのエントリーポイントを MCP クライアントに指定します。

node /absolute/path/to/twitter-mcp/dist/cli.js

ソースを変更するたびに npm run build を実行してください。クライアントの stdio コマンドとして src や npm run dev を使用しないでください。標準出力にビルドログが出力されると、MCP メッセージが破損することがあります。

クライアントの設定

各例は npm パッケージを使う設定から始まり、続いてローカル環境での設定を示します。/absolute/path/to/twitter-mcp をクローンのパスに、your_key_here を Rettiwt キーに置き換えてください。キーを含む設定ファイルをコミットしないでください。

Claude

Claude Code に npm パッケージを追加します。

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- npx -y @granitebps/twitter-mcp

ローカルビルドの場合：

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- node /absolute/path/to/twitter-mcp/dist/cli.js

Claude Code のデフォルトのスコープはローカルです。プロジェクト間でサーバーを利用できるようにするには、twitter の前に --scope user を追加してください。

Claude Desktop は同じサーバーを claude_desktop_config.json から読み込みます。ファイルを編集した後、アプリを再起動してください。

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

ローカルビルドの場合は、command と args を次のように置き換えてください。

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Codex

npm パッケージを ~/.codex/config.toml、または信頼済みプロジェクト内の .codex/config.toml に追加します。

[mcp_servers.twitter]
command = "npx"
args = ["-y", "@granitebps/twitter-mcp"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

ローカルビルドの場合：

[mcp_servers.twitter]
command = "node"
args = ["/absolute/path/to/twitter-mcp/dist/cli.js"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

ファイルを編集した後、Codex を再起動してください。同じコンピューターでは、CLI、IDE 拡張機能、デスクトップアプリでこの設定が共有されます。

OpenCode

npm パッケージを opencode.json または opencode.jsonc に追加します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "twitter": {
      "type": "local",
      "command": ["npx", "-y", "@granitebps/twitter-mcp"],
      "enabled": true,
      "environment": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

ローカルビルドの場合は、command 配列を次のように置き換えてください。

{
  "command": ["node", "/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Cursor

プロジェクト内の .cursor/mcp.json、またはグローバルに使用する場合は ~/.cursor/mcp.json に npm パッケージを追加します。

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

ローカルビルドの場合は、command と args を次のように置き換えてください。

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

プロバイダー

モード	選択方法	認証情報	備考
Rettiwt	デフォルト、または TWITTER_MODE=rettiwt	RETTIWT_API_KEY	X API の料金はかかりません。非公式の内部エンドポイントを使用するため、動作しなくなったり、アカウントが危険にさらされたりする可能性があります。
Official API	TWITTER_MODE=api	ベアラートークン、または OAuth 認証情報一式	サポートされている X API を使用します。アクセスレベルと料金は X が管理します。

Rettiwt のセットアップ

このサーバーで Rettiwt を使うには、認証済みユーザーモードが必要です。ゲストモードには対応していません。

1. Rettiwt の認証手順に従って API キーを生成します。
2. MCP クライアントの環境変数として RETTIWT_API_KEY に設定します。
3. TWITTER_MODE を設定せずにサーバーを起動するか、明示的に TWITTER_MODE=rettiwt を設定します。

Rettiwt キーには X のセッション Cookie が含まれており、アカウントと同等のアクセス権があります。パスワードと同様に扱ってください。コミットしたり、課題に貼り付けたり、ログに記録したり、コマンドライン引数として渡したりしないでください。自分が所有するアカウント、またはアクセス許可を得ているアカウントのキーのみを使用してください。

Rettiwt は非公式です。X の自動化ルールでは、API を使用しないウェブサイトの自動化が禁止されており、違反するとアカウントが停止される可能性があると警告されています。このモードを使用する前に、X ルールをお読みください。コンプライアンス上のリスクとアカウントへのリスクは、ご自身で受け入れる必要があります。

Official X API のセットアップ

ベアラートークンを使用します。

TWITTER_MODE=api
TWITTER_BEARER_TOKEN=your_bearer_token

または、OAuth 認証情報一式を指定します。

TWITTER_MODE=api
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_SECRET=your_access_secret

X Developer Portalで認証情報を作成します。API へのアクセスと料金は X が管理するため、このモードを選択する前に最新の利用条件を確認してください。

設定

変数	必須	説明
TWITTER_MODE	いいえ	デフォルトは rettiwt、または api です。それ以外の値では起動に失敗します。
RETTIWT_API_KEY	Rettiwt モード	認証済み Rettiwt セッションキーです。
TWITTER_BEARER_TOKEN	API モードの選択肢	Official API のベアラートークンです。
TWITTER_API_KEY	OAuth の選択肢	OAuth アプリケーションキーです。
TWITTER_API_SECRET	OAuth の選択肢	OAuth アプリケーションシークレットです。
TWITTER_ACCESS_TOKEN	OAuth の選択肢	OAuth アクセストークンです。
TWITTER_ACCESS_SECRET	OAuth の選択肢	OAuth アクセスシークレットです。
TWITTER_REQUEST_TIMEOUT_MS	いいえ	1,000～120,000 ms のリクエスト期限です。デフォルト：30,000。

サーバーは、不完全な OAuth 設定を起動時に拒否します。認証情報はプロセス環境から読み込まれ、get_server_info を通じて返されることはありません。

ツール

ツール	入力	結果
get_tweet	tweet_id	1件の投稿です。数値 ID、または x.com もしくは twitter.com のステータス URL を指定できます。
get_tweet_replies	tweet_id、任意の max_results	返信と利用可能なページメタデータです。
get_user_profile	username	1件の公開プロフィールです。先頭に @ を付けても指定できます。
search_tweets	query、任意の max_results	条件に一致する投稿と利用可能なページメタデータです。検索演算子はプロバイダーによって異なります。
get_server_info	なし	バージョン、アクティブなプロバイダー、ツール、制限、機能です。

max_results のデフォルトは 10 で、1〜100 の値を指定できます。呼び出しが成功すると、構造化された MCP コンテンツと、旧クライアント向けの JSON テキストが返されます。コレクションツールは項目を JSON テキストで返し、カーソルと警告を構造化コンテンツに格納します。

Rettiwt モードでは、get_tweet、get_tweet_replies、search_tweets が返す投稿に、プロバイダーから提供された場合は任意の media 配列も含まれます。各項目には id、type（PHOTO、VIDEO、または GIF）、直接アクセスできる url、動画プレビュー用の任意の thumbnail_url が含まれます。サーバーはメディアへのリンクを返します。ファイルはダウンロードしません。公式 API モードでは、現在、添付メディアは返されません。

1.x リリース系列 の安定したツール、入力、出力、エラーの動作については、v1 互換性契約に記載されています。

エラー

ツールの失敗には、安定したコードが使用されます。

• INVALID_INPUT
• AUTH_REQUIRED
• AUTH_FAILED
• NOT_FOUND
• RATE_LIMITED
• UPSTREAM_UNAVAILABLE
• TIMEOUT
• UNSUPPORTED_OPERATION
• INTERNAL_ERROR

エラーにはプロバイダー名が含まれ、再試行が有効な可能性があるかどうかがクライアントに通知されます。認証情報や上流からのレスポンス本文そのものは含まれません。

アーキテクチャ

stdio CLI
  -> validated environment configuration
  -> MCP server and tool handlers
  -> TwitterProvider contract
       -> Rettiwt adapter
       -> official X API adapter

ドメインスキーマは、どちらのプロバイダーにも依存しません。各プロバイダーアダプターは上流データをマッピングし、制限と期限を適用し、エラーを変換します。src/index.ts をインポートしてもサーバーは起動しません。

開発

npm ci
npm run check

npm run check は、フォーマット、リント、型、カバレッジ、本番ビルド、npm パッケージの内容、およびクリーンな tarball のインストールをチェックします。デフォルトのテストスイートはフェイクを使用するため、X の認証情報は必要ありません。

目的に合わせて実行できるコマンド：

npm test
npm run typecheck
npm run lint
npm run build
npm run check:package
npm run check:install
npx @modelcontextprotocol/inspector node dist/cli.js

Rettiwt ライブスモークテスト

ライブスモークテストでは、コンパイル済みの stdio サーバーを起動し、get_tweet、get_tweet_replies、get_user_profile、search_tweets を呼び出します。選択した投稿からユーザー名と検索クエリを取得します。

RETTIWT_API_KEY=your_key_here \
TWITTER_LIVE_TWEET_ID=1234567890123456789 \
npm run test:live

作成者のプロフィールが引き続き利用可能な公開投稿を選んでください。どちらかの変数が設定されていない場合、ライブサーバーの起動やネットワークリクエストの実行前にコマンドは停止します。このテストは npm run check や通常の CI の一部としては実行されません。

リリースの検証

自動テストスイートでは、設定、プロバイダーアダプター、MCP 呼び出し、コンパイル済み stdio エントリーポイント、npm tarball からのインストールをテストします。Rettiwt ライブスモークテストは任意であり、通常の CI では実行されません。バージョン 1.0.0 は、上流サービスへのライブ検証を行わずに準備されました。

メンテナーは、承認済みタグを使用した npm、MCP Registry、GitHub のリリース手順について、リリースガイドを参照できます。ライブテストではリポジトリのシークレットから認証情報を読み込む必要があり、信頼できないプルリクエストに対して実行してはなりません。

トラブルシューティング

Rettiwt キーが見つからない場合

起動時に RETTIWT_API_KEY is required in rettiwt mode と表示される場合は、MCP クライアントの設定でキーを設定してください。デスクトップクライアントは、シェルの .env ファイルを自動的に引き継ぎません。

Rettiwt の認証が無効な場合

Invalid authentication data または AUTH_FAILED と表示された場合は、新しい Rettiwt キーを生成し、X のセッションが引き続き機能することを確認してください。問題が発生したキーをイシューに投稿しないでください。

レート制限

RATE_LIMITED が表示された場合は、再試行する前に待機し、リクエスト頻度を下げてください。プロバイダーから値が返される場合は、retryAfterSeconds を確認してください。

公式 API の 401 または 403

認証情報の設定、アプリの権限、エンドポイントへのアクセス、現在の X API プランを確認してください。

Node エンジンの警告

パッケージと Rettiwt のエンジン要件を満たすには、Node.js 22.21.0 またはそれ以降の Node 22 リリースを使用してください。Node 24.19.0 はランタイムテストに合格していますが、Node 24 でのインストールでは engine-strict により警告が表示されたり、失敗したりする場合があります。Node 24 との互換性 を参照してください。

ライセンス

ISC