X (Twitter) MCP Server

X (Twitter) MCP サーバー

プロフェッショナルなワークフロー自動化、強化されたエラー処理、リアルタイムドキュメントを備えた、X（Twitter）API 統合のための包括的な Model Context Protocol サーバー実装です。

🚀 特長

• 合計53個のツール - Twitter API 33個 + 強化された SocialData.tools のリサーチ機能20個
• 高度な分析 - スレッド分析、ネットワークマッピング、センチメント分析、バイラル追跡
• API の制限を回避 - 強化されたリサーチツールは Pro ティアの要件なしで動作します
• プロフェッショナルなエラー処理 - 明確なアップグレード案内と柔軟な API キー処理
• 5個のワークフロープロンプト - すぐに使える自動化テンプレート
• 6個の動的リソース - リアルタイムの API ドキュメントとステータス
• MCP に完全準拠 - ツール、プロンプト、リソースをサポート

📋 クイックスタート

前提条件

• Node.js 18+
• npm または yarn
• X (Twitter) API 認証情報（最低 Basic ティア - 月額 $200）

ローカルインストール

1. クローンしてインストール

   git clone <repository-url>
   cd twitter-server
   npm install
   

2. 環境を設定

   cp .env.example .env
   # Edit .env with your credentials
   

   必須の環境変数：

   # Twitter API credentials (Required)
   X_API_KEY=your_api_key_here
   X_API_SECRET=your_api_secret_here  
   X_ACCESS_TOKEN=your_access_token_here
   X_ACCESS_TOKEN_SECRET=your_access_token_secret_here
   
   # SocialData.tools API key (Optional - enables enhanced research tools)
   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   SOCIALDATA_BASE_URL=https://api.socialdata.tools  # Optional, uses default if not set
   

3. ビルドして実行

   npm run build
   npm start
   

4. サーバーをテスト

   # Test with JSON-RPC calls
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js
   
   # Test specific tool
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js
   

🔑 X (Twitter) API のセットアップ

必要な認証情報

.env ファイルに以下を追加します：

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

API アクセスレベル

ティア	費用	動作するツール	制限のあるツール
Basic	月額 $200	18/22個のツール	searchTweets, getHashtagAnalytics
Pro	月額 $5,000	22個すべてのツール	なし

🛠️ 利用可能なツール（合計53個）

🐦 Twitter API ツール（33個）

✅ ツイート操作（すべて動作）

• postTweet - 新しいツイートを投稿
• getTweetById - 特定のツイートを取得
• replyToTweet - ツイートに返信
• deleteTweet - 自分のツイートを削除

✅ エンゲージメント（すべて動作）

• likeTweet / unlikeTweet - ツイートに「いいね」する／取り消す
• retweet / undoRetweet - リツイートする／取り消す
• getRetweets - リツイートしたユーザーを取得

✅ ユーザー管理（ほとんど動作）

• getUserInfo - ユーザープロフィールを取得 ✅
• getUserTimeline - ユーザーのツイートを取得 ✅
• followUser / unfollowUser - ユーザーをフォローする／解除する ✅
• getFollowers - フォロワーを取得 ⚠️（403 - 特別な権限が必要）
• getFollowing - フォロー中のユーザーを取得 ⚠️（403 - 特別な権限が必要）

✅ リスト管理（すべて動作）

• createList - X (Twitter) リストを作成
• getUserLists - ユーザーのリストを取得
• addUserToList / removeUserFromList - リストメンバーを管理
• getListMembers - リストメンバーを取得

⚠️ 検索と分析（制限あり）

• searchTweets - ツイートを検索（Pro ティアが必要 - 月額 $5,000）
• getHashtagAnalytics - ハッシュタグ分析（Pro ティアが必要）
• getLikedTweets - 「いいね」したツイートを取得（API アクセスの問題）

🔍 SocialData.tools による強化されたリサーチ（20個のツール）

注：これらのツールは API キーがない場合、役立つセットアップ手順を表示して柔軟に対応します

🔎 高度な検索（6個のツール）

• advancedTweetSearch - 演算子を使った複雑なクエリ。API ティアの制限を回避します
• historicalTweetSearch - 標準 API の制限を超えて過去のツイートにアクセス
• trendingTopicsSearch - リアルタイムのトレンド分析と人気コンテンツの発見
• bulkUserProfiles - 1回のリクエストで複数ユーザーのプロフィールを分析
• userGrowthAnalytics - 時間の経過に伴うユーザー成長パターンを分析
• userInfluenceMetrics - エンゲージメントスコアと影響力を算出

🧵 スレッドと会話の分析（3個のツール）

• getFullThread - エンゲージメント指標とともに Twitter スレッド全体を再構成
• getConversationTree - 返信や引用を含む会話構造をマッピング
• getThreadMetrics - スレッドのパフォーマンス分析とエンゲージメントの分布

🌐 ネットワーク分析（3個のツール）

• findMutualConnections - インタラクションを通じて相互のつながりを発見
• analyzeFollowerDemographics - フォロワーの傾向と属性を分析
• mapInfluenceNetwork - 影響力のマッピングとつながりの強さを分析

📈 高度な分析（3 ツール）

• getHashtagTrends - トレンド分析によるハッシュタグのパフォーマンス追跡
• analyzeSentiment - キーワードの出現頻度追跡を備えたセンチメント分析
• trackVirality - 拡散パターンとエンゲージメント速度の分析

📱 ダイレクトメッセージとモデレーション（5 ツール）

• 各種 DM およびユーザーモデレーションツール

🔑 API キーの設定

Twitter API（必須）

Twitter Developer Portal から取得してください：

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

SocialData.tools API（任意）

Twitter API の制限を回避する、20 個の拡張リサーチツールが利用可能になります：

1. SocialData.tools でサインアップします
2. ダッシュボードからAPI キーを取得します
3. .env ファイルに追加します：

   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   

SocialData API キーがない場合： 拡張リサーチツールはエラーの代わりに、役立つセットアップ手順を表示します。

🧪 SocialData.tools 統合のテスト

拡張リサーチツールのテスト

# Test advanced tweet search (bypasses Twitter API Pro tier requirement)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "AI OR machine learning", "maxResults": 5}}}' | node dist/index.js

# Test sentiment analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "analyzeSentiment", "arguments": {"query": "ChatGPT", "sampleSize": 20}}}' | node dist/index.js

# Test user influence metrics
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "userInfluenceMetrics", "arguments": {"username": "openai"}}}' | node dist/index.js

# Test thread analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getFullThread", "arguments": {"tweetId": "1234567890123456789"}}}' | node dist/index.js

API キーなしでのテスト

# These will show helpful setup instructions instead of errors
SOCIALDATA_API_KEY="" echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "test"}}}' | node dist/index.js

🆚 使用するツールの選び方

Twitter API と SocialData.tools の比較

用途	Twitter API ツール	SocialData.tools の代替ツール	メリット
基本的な検索	searchTweets ⚠️（Pro tier、月額 $5k）	advancedTweetSearch ✅	API の制限を回避
ユーザー分析	getUserInfo ✅	userInfluenceMetrics ✅	高度な分析
過去のデータ	API ティアによる制限あり	historicalTweetSearch ✅	古いツイートにアクセス可能
センチメント分析	利用不可	analyzeSentiment ✅	センチメントのスコアリング機能を内蔵
スレッド分析	手動で再構成	getFullThread ✅	スレッドを自動でマッピング
ネットワークのマッピング	利用不可	mapInfluenceNetwork ✅	つながりを分析
ハッシュタグのトレンド	getHashtagAnalytics ⚠️（Pro tier）	getHashtagTrends ✅	ティアによる制限なし

おすすめのワークフロー

1. 投稿、エンゲージメント、基本操作には、まずTwitter API ツールを使用します
2. リサーチ、分析、高度なインサイトにはSocialData.toolsを使用します
3. 包括的な Twitter の自動化と分析には、両方を組み合わせて使用します

🎯 MCP ワークフローのプロンプト

このサーバーには、プロフェッショナルなワークフローテンプレートが 5 種類含まれています：

1. ツイートの作成（compose-tweet）

ハッシュタグ、メンション、メディアを含む魅力的なツイートを作成するための対話型ガイダンスです。

2. 分析レポート（analytics-report）

ビジネスインサイトを得るための、包括的な X（Twitter）分析ワークフローです。

3. コンテンツ戦略（content-strategy）

戦略的なコンテンツ計画とオーディエンスエンゲージメントのワークフローです。

4. コミュニティ管理（community-management）

カスタマーサービスとコミュニティエンゲージメントのベストプラクティスです。

5. ハッシュタグのリサーチ（hashtag-research）

業界に特化したハッシュタグのリサーチとトレンド分析です。

📊 動的リソース

MCP 経由でアクセスできるリアルタイム情報：

• API レート制限 - 使用状況をリアルタイムで監視
• アクセスレベルのステータス - 現在のティアで利用可能な機能
• ツールのステータスレポート - 動作中のツールと制限付きツール
• クイックスタートガイド - 利用開始のためのドキュメント
• ワークフローテンプレート - あらかじめ用意された自動化の例
• ユーザープロフィールデータ - 動的なユーザー情報（API をリアルタイムで呼び出し）

🧪 テスト

手動テスト

# Test working tools
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "postTweet", "arguments": {"text": "Hello from MCP!"}}}' | node dist/index.js

# Test user info
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

# Test limited tools (will show upgrade guidance)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "searchTweets", "arguments": {"query": "MCP"}}}' | node dist/index.js

テスト結果の概要

• Basic tier で 18 個のツールが動作
• API ティアや権限により 4 個のツールに制限あり
• アップグレード方法を案内する分かりやすいエラーメッセージ
• すべてのコア機能が動作

🔧 統合例

MCP クライアント（Cursor/Claude）

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/path/to/twitter-server/dist/index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret", 
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

直接 JSON-RPC を使用

# Always source environment first
source .env

# List all tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# Call specific tool
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "toolName", "arguments": {"param": "value"}}}' | node dist/index.js

📝 API ドキュメント

ツイート操作

postTweet

{
  "text": "Your tweet content (up to 280 characters)"
}

getTweetById

{
  "tweetId": "1234567890123456789",
  "tweetFields": ["created_at", "public_metrics", "author_id"]
}

replyToTweet

{
  "tweetId": "1234567890123456789", 
  "text": "Your reply content"
}

ユーザー操作

getUserInfo

{
  "username": "elonmusk",
  "fields": ["description", "public_metrics", "profile_image_url"]
}

followUser

{
  "username": "target_username"
}

エンゲージメント

likeTweet

{
  "tweetId": "1234567890123456789"
}

retweet

{
  "tweetId": "1234567890123456789"
}

🚨 エラー処理

プロフェッショナルなエラーメッセージ

強化されたエラーハンドリングにより、次の情報を提供します。

• 利用制限のあるツールについて、API ティアを明確に説明
• アップグレード料金の情報（Pro ティアは月額 $5,000）
• Twitter Developer Portal への直接アップグレードリンク
• 代替ソリューションの提案

エラーレスポンスの例：

{
  "error": "This endpoint requires X (Twitter) API Pro tier access ($5,000/month). Visit https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api#v2-access-leve to upgrade your access level."
}

📁 プロジェクト構成

twitter-server/
├── src/
│   ├── handlers/          # API endpoint handlers
│   ├── prompts.ts        # MCP workflow prompts  
│   ├── resources.ts      # Dynamic MCP resources
│   └── index.ts          # Main MCP server
├── dist/                 # Compiled JavaScript
├── scripts/              # Documentation & PRD
└── package.json

🔄 開発

ビルドと実行

npm run build    # Compile TypeScript
npm start        # Start production server
npm run dev      # Development mode with watch

新しいツールの追加

1. 適切な src/handlers/ ファイルにハンドラー関数を追加します
2. src/index.ts でツールを登録します
3. この README にドキュメントを追加します
4. JSON-RPC 呼び出しでテストします

コントリビューション

1. 既存のコードパターンに従ってください
2. プロフェッショナルなメッセージを含む、適切なエラーハンドリングを追加してください
3. 正常なケースと失敗するケースの両方でテストしてください
4. ドキュメントを更新してください

📋 既知の制限事項

API ティアの制限

• searchTweets：Pro ティアが必要です（月額 $5,000）
• getHashtagAnalytics：Pro ティアが必要です
• getFollowers/getFollowing：特別な権限が必要です（403 エラー）
• getLikedTweets：パラメーターの検証に問題があります

推奨事項

• 現在のセットアップ：基本的な X（Twitter）自動化に最適です
• 高度な分析を行う場合：Pro ティアへのアップグレードをご検討ください
• フォロワー／フォロー中のユーザーを取得する場合：権限の引き上げを申請してください

🆘 トラブルシューティング

よくある問題

エラー：「fetch is not defined」

# Ensure Node.js 18+ 
node --version

403 権限エラー

• API 認証情報が正しいことを確認してください
• アカウントに必要な権限があることを確認してください
• 一部のエンドポイントには特別な承認が必要です

400 Bad Request エラー

• パラメーターの形式を確認してください
• 強化されたエラーメッセージの案内を確認してください
• API ティアがそのエンドポイントに対応していることを確認してください

ヘルプの利用

1. エラーメッセージを確認する — 強化されたエラーハンドリングにより、明確な案内を提供します
2. API ドキュメントを確認する — X（Twitter）Developer Portal
3. まず正常に動作するツールでテストする — 基本設定が正しいことを確認します
4. 環境変数を確認する — すべての認証情報が設定されていることを確認します

---

📊 現在の状況

• ツール総数 53 個：Twitter API 33 個 ＋ SocialData.tools の強化されたリサーチツール 20 個
• 高度な分析：スレッド分析、ネットワークマッピング、感情分析、バイラルトラッキング
• API キーがない場合の適切な処理：強化ツールでは、API キーがない場合に役立つセットアップ手順を表示します
• API 制限を回避：リサーチツールは Twitter Pro ティアの要件なしで動作します
• プロフェッショナルなエラーハンドリング：明確なアップグレード案内とわかりやすいメッセージ
• MCP に完全準拠：ツール、プロンプト、リソース
• 本番環境での利用に対応：信頼性を高め、包括的な分析と優れた UX を実現

Model Context Protocol と SocialData.tools の統合を使用して、❤️ を込めて構築されました