agent-twitter-client-mcp

agent-twitter-client-mcp

agent-twitter-client パッケージを使用して Twitter と連携し、AI モデルが API に直接アクセスすることなく Twitter を利用できるようにする Model Context Protocol（MCP）サーバーです。

特長

• 認証方法：

  • Cookie 認証（推奨）
  • ユーザー名とパスワードによる認証
  • Twitter API v2 の認証情報

• ツイート操作：

  • ユーザーのツイートを取得
  • ID を指定してツイートを取得
  • ツイートを検索
  • テキストやメディアを含むツイートを送信
  • 投票を作成
  • ツイートに「いいね」、リツイート、引用ツイート

• ユーザー操作：

  • ユーザープロフィールを取得
  • ユーザーをフォロー
  • フォロワーとフォロー中のユーザーのリストを取得

• Grok との連携：

  • Twitter のインターフェースを通じて Grok とチャット
  • 会話 ID を使って会話を続ける
  • ウェブ検索結果と引用を取得
  • Grok を通じて Twitter のリアルタイムデータにアクセス
  • 注：Grok の機能には agent-twitter-client v0.0.19 以降が必要です

ドキュメント

• 開発者ガイド - 開発者向けの詳細ガイド
• テストガイド - MCP のテスト方法
• エージェントガイド - Twitter MCP の使用方法に関する AI エージェント向けガイド
• コントリビューションガイド - このプロジェクトへの貢献に関するガイドライン
• 変更履歴 - このプロジェクトの変更履歴
• デモ README - デモスクリプトの実行ガイド
• Grok の例 - Grok AI 連携の例に関するドキュメント

クイックスタート

インストール

# Install globally
npm install -g agent-twitter-client-mcp

# Or install locally
npm install agent-twitter-client-mcp

基本的な使い方

1. Twitter の認証情報を含む .env ファイルを作成します（認証方法を参照）
2. MCP サーバーを実行します。

# If installed globally
agent-twitter-client-mcp

# If installed locally
npx agent-twitter-client-mcp

デモスクリプト

このパッケージには、さまざまな機能を紹介するサンプルスクリプトを含む demo ディレクトリがあります。

# Clone the repository to access the demo scripts
git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp/demo

# Run the interactive demo menu
./run-demo.sh

# Run a specific demo script
./run-demo.sh --script tweet-search.js

# Run Grok AI examples (requires agent-twitter-client v0.0.19)
./run-demo.sh --script simple-grok.js --use-local-agent-twitter-client
./run-demo.sh --script grok-chat.js --use-local-agent-twitter-client

詳しくは、デモ READMEを参照してください。

ポートの設定

デフォルトでは、MCP サーバーはポート 3000 で実行されます。この設定を変更する必要がある場合（たとえば、ポート 3000 ですでにアプリケーションが実行されている場合）、いくつかの方法があります。

方法 1：環境変数を使用する

PORT 環境変数を設定します。

PORT=3001 npx agent-twitter-client-mcp

方法 2：Docker Compose を使用する

Docker Compose を使用する場合は、.env ファイルでホスト側とコンテナ側の両方のポートを設定できます。

# .env file
MCP_HOST_PORT=3001    # The port on your host machine
MCP_CONTAINER_PORT=3000  # The port inside the container

続いて、次を実行します。

docker-compose up -d

これにより、ホストのポート 3001 がコンテナ内のポート 3000 に割り当てられます。ほかのアプリケーションでポート 3000 を引き続き使用しながら、http://localhost:3001 で MCP にアクセスできます。

Claude Desktop のセットアップ

1. 設定ファイルに次の内容を追加して、この MCP を使用するよう Claude Desktop を設定します。

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

{
  "mcpServers": {
    "agent-twitter-client-mcp": {
      "command": "npx",
      "args": ["-y", "agent-twitter-client-mcp"],
      "env": {
        "AUTH_METHOD": "cookies",
        "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
      }
    }
  }
}

2. Claude Desktop を再起動します。

認証方法

Cookie 認証（推奨）

{
  "AUTH_METHOD": "cookies",
  "TWITTER_COOKIES": "[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\", \"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\"]"
}

Cookie を取得するには：

1. ブラウザーで Twitter にログインします
2. 開発者ツールを開きます（F12）
3. ［Application］タブ > ［Cookies］を開きます
4. auth_token、ct0、twid Cookie の値をコピーします
5. 各 Cookie に Domain=.twitter.com の部分も含めてください

ユーザー名とパスワードによる認証

{
  "AUTH_METHOD": "credentials",
  "TWITTER_USERNAME": "your_username",
  "TWITTER_PASSWORD": "your_password",
  "TWITTER_EMAIL": "[email protected]", // Optional
  "TWITTER_2FA_SECRET": "your_2fa_secret" // Optional, required if 2FA is enabled
}

Twitter API による認証

{
  "AUTH_METHOD": "api",
  "TWITTER_API_KEY": "your_api_key",
  "TWITTER_API_SECRET_KEY": "your_api_secret_key",
  "TWITTER_ACCESS_TOKEN": "your_access_token",
  "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret"
}

利用可能なツール

• get_user_tweets：特定のユーザーのツイートを取得
• get_tweet_by_id：IDを指定して特定のツイートを取得
• search_tweets：ツイートを検索
• send_tweet：新しいツイートを投稿
• send_tweet_with_poll：投票付きのツイートを投稿
• like_tweet：ツイートに「いいね」する
• retweet：ツイートをリツイート
• quote_tweet：ツイートを引用
• get_user_profile：ユーザーのプロフィールを取得
• follow_user：ユーザーをフォロー
• get_followers：ユーザーのフォロワーを取得
• get_following：ユーザーがフォローしているユーザーを取得
• grok_chat：Twitter経由でGrokとチャット
• health_check：Twitter MCP サーバーの状態を確認

テストインターフェース

MCPには、テスト用の対話型コマンドラインインターフェースが含まれています。

npx agent-twitter-client-mcp-test
# or if installed locally
npm run test:interface

これによりREPLが起動し、さまざまなMCP機能をテストできます。

agent-twitter-client-mcp> help

Available commands:
  health                     Run a health check
  profile <username>         Get a user profile
  tweets <username> [count]  Get tweets from a user
  tweet <id>                 Get a specific tweet by ID
  search <query> [count]     Search for tweets
  post <text>                Post a new tweet
  like <id>                  Like a tweet
  retweet <id>               Retweet a tweet
  quote <id> <text>          Quote a tweet
  follow <username>          Follow a user
  followers <userId> [count] Get a user's followers
  following <userId> [count] Get users a user is following
  grok <message>             Chat with Grok
  help                       Show available commands
  exit                       Exit the test interface

テストコマンドの例

# Run a health check
agent-twitter-client-mcp> health

# Search for tweets
agent-twitter-client-mcp> search mcp 2

# Get a user's profile
agent-twitter-client-mcp> profile elonmusk

# Get tweets from a user
agent-twitter-client-mcp> tweets openai 5

# Chat with Grok
agent-twitter-client-mcp> grok Explain quantum computing in simple terms

使用例

Claudeに次のように依頼できます。

• 「TwitterでAIについてのツイートを検索して」
• 「『Hello from Claude!』とツイートして」
• 「@OpenAIの最新ツイートを取得して」
• 「量子コンピューティングについてGrokとチャットして」

応用的な使い方

メディアの操作

画像付きのツイートを投稿するには：

I want to post a tweet with an image. The tweet should say "Beautiful sunset today!" and include this image.

動画付きのツイートを投稿するには：

I want to post a tweet with a video. The tweet should say "Check out this amazing video!" and include the video file.

投票の作成

投票を作成するには：

Create a Twitter poll asking "What's your favorite programming language?" with options: Python, JavaScript, Rust, and Go. The poll should run for 24 hours.

Grokとのやり取り

Grokと会話するには：

Use Grok to explain quantum computing to me. Ask it to include some real-world applications.

Grokとの会話を続けるには：

Continue the Grok conversation and ask it to elaborate on quantum entanglement.

Grok独自の機能

Twitter上のGrokは、単独のGrok APIでも利用できないリアルタイムのTwitterデータにアクセスできます。そのため、Grokには次のようなことを尋ねられます。

• Twitterで現在トレンドになっているトピック
• 特定の話題に関する最近のツイートの分析
• Twitterユーザーとその投稿内容に関する情報
• プラットフォーム上で話題になっているリアルタイムの出来事

クエリの例：

• 「今、Twitterでトレンドになっているトピックは？」
• 「Twitter上のAIに関する感情を分析して」
• 「最新のAppleイベントについて、みんなは何と言っている？」
• 「今日話題になっている人気のミームコインについて教えて」

Grokの認証要件

Grok機能を利用するには、適切な認証が必要です。MCPでは次の2つの方法をサポートしています。

1. Cookie認証（推奨）：

   • CookieはJSON配列形式にする必要があります
   • 例：TWITTER_COOKIES=["auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com", "ct0=YOUR_CT0_VALUE; Domain=.twitter.com", "twid=u%3DYOUR_USER_ID; Domain=.twitter.com"]
   • 必須のCookieはauth_token、ct0、twidです

2. ユーザー名／パスワード認証：

   • 環境にTWITTER_USERNAMEとTWITTER_PASSWORDを設定します
   • 場合によってはCloudflareの保護により認証できないことがあります

Grokのレート制限

Grokには利用に影響する可能性があるレート制限があります。

• 非プレミアムアカウント：2時間あたり25メッセージ
• プレミアムアカウント：より高い制限

制限に達すると、MCPはレスポンスにレート制限の情報を返します。

Grokの使用方法の詳細については、Grokの使用例のドキュメントを参照してください。

トラブルシューティング

認証の問題

Cookie認証の問題

Cookie認証で問題が発生している場合：

1. Cookieの有効期限：TwitterのCookieは通常、一定期間が経過すると期限切れになります。Twitterからログアウトして再度ログインし、Cookieを更新してください。
2. Cookieの形式：Cookieが、正しいドメインを含む文字列のJSON配列として適切にフォーマットされていることを確認してください。
3. 必須Cookie：必須のCookieであるauth_token、ct0、twidが含まれていることを確認してください。

正しくフォーマットされたCookieの例：

"TWITTER_COOKIES": "[\"auth_token=1234567890abcdef; Domain=.twitter.com\", \"ct0=abcdef1234567890; Domain=.twitter.com\", \"twid=u%3D1234567890; Domain=.twitter.com\"]"

認証情報による認証の問題

ユーザー名／パスワード認証で問題が発生している場合：

1. 2要素認証：アカウントで2FAが有効になっている場合は、TWITTER_2FA_SECRETを指定する必要があります。
2. アカウントのロック：ログインに何度も失敗すると、アカウントがロックされることがあります。アカウント確認の依頼が届いていないか、メールを確認してください。
3. CAPTCHAの確認：TwitterでCAPTCHAによる確認が表示されることがありますが、クライアントでは自動的に対応できません。

API 認証の問題

API 認証の問題については、以下を確認してください。

1. API キーの権限：実行しようとしている操作に必要な権限が API キーに付与されていることを確認してください。
2. レート制限：Twitter API にはレート制限があり、上限を超えると失敗する場合があります。
3. API の変更：Twitter は API を変更することがあり、互換性の問題が発生する場合があります。

操作エラー

ツイートの投稿に失敗する場合

ツイートを投稿できない場合は、以下を確認してください。

1. コンテンツの制限：Twitter は、コンテンツポリシーに違反するツイートをブロックする場合があります。
2. メディア形式の問題：メディアが適切な形式でエンコードされていることを確認してください。
3. レート制限：Twitter は投稿頻度を制限しています。

検索の問題

検索が機能しない場合は、以下を確認してください。

1. クエリの構文：検索クエリが Twitter の検索構文に従っていることを確認してください。
2. 検索の制限：検索モードによっては、制限があったり、特定の権限が必要になったりする場合があります。

Grok の問題

Grok の機能が動作しない場合は、以下を確認してください。

1. バージョン要件：

   • Grok には agent-twitter-client v0.0.19 以降が必要です
   • 現在のパッケージは、基本機能のために v0.0.18 を使用しています
   • デモスクリプトでは、--use-local-agent-twitter-client フラグを使って、一時的に v0.0.19 をインストールしてください

2. 認証の問題：

   • Cookie の形式：Cookie が正しい JSON 配列形式になっていることを確認してください
   • Cookie の有効性：Twitter の Cookie は一定期間が経過すると有効期限が切れます
   • Cloudflare による保護：ユーザー名とパスワードによる認証は、Cloudflare にブロックされる場合があります
   • Premium の要件：Grok にアクセスするには、Twitter Premium のサブスクリプションが必要です

3. レート制限：

   • 非 Premium アカウント：2 時間あたり 25 メッセージ
   • エラーメッセージ：「レート制限中です：上限に達しました…」
   • 解決方法：レート制限がリセットされるまで待つか、Premium アカウントにアップグレードしてください

4. 環境ファイルの場所：

   • デモスクリプトでは、認証情報がルートの .env ファイルではなく、demo/.env にあることを確認してください
   • --debug-env フラグを使って、読み込まれている環境変数を確認してください

Grok の問題の詳しいトラブルシューティングについては、Grok の例のドキュメントを参照してください。

サーバーの問題

ヘルスチェック

health_check ツールを使って、サーバーの問題を診断してください。

Run a health check on the agent-twitter-client-mcp server to diagnose any issues.

ヘルスチェックでは、以下が報告されます。

• 認証状態
• API 接続状態
• メモリ使用量

ログ

サーバーはコンソールとファイルの両方にログを出力します。

• error.log：エラーレベルのメッセージが含まれます
• combined.log：すべてのログメッセージが含まれます

詳細なエラー情報については、これらのログを確認してください。

開発

前提条件

• Node.js 18+
• npm

セットアップ

1. リポジトリをクローンします

git clone https://github.com/ryanmac/agent-twitter-client-mcp.git
cd agent-twitter-client-mcp

2. 依存関係をインストールします

npm install

3. 設定を記述した .env ファイルを作成します。

AUTH_METHOD=cookies
TWITTER_COOKIES=["cookie1=value1", "cookie2=value2"]

4. プロジェクトをビルドします

npm run build

5. サーバーを起動します

npm start

環境変数

認証変数に加えて、以下を設定できます。

• LOG_LEVEL：ログレベルを設定します（error、warn、info、debug）
• NODE_ENV：環境を設定します（development、production）

Docker

Docker を使ってサーバーを実行することもできます。

Docker を直接使う

# Build the Docker image
docker build -t agent-twitter-client-mcp .

# Run the container with environment variables
docker run -p 3000:3000 \
  -e AUTH_METHOD=cookies \
  -e TWITTER_COOKIES='["auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com", "ct0=YOUR_CT0_VALUE; Domain=.twitter.com"]' \
  agent-twitter-client-mcp

Docker Compose を使う

1. Twitter の認証情報を記述した .env ファイルを作成します
2. docker-compose で実行します。

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Docker の環境変数

Docker コンテナには、いくつかの方法で環境変数を渡すことができます。

1. docker-compose.yml ファイル内（設定済み）
2. .env ファイルを使用（docker-compose での使用を推奨）
3. docker run コマンドに直接指定（上記の例を参照）

ログの永続化

docker-compose の設定には、ログ用のボリュームマウントが含まれています。

volumes:
  - ./logs:/app/logs

これにより、プロジェクトフォルダー内の logs ディレクトリにログが保存されます。

セキュリティに関する考慮事項

• 認証情報の保存：認証情報は安全に保存し、環境変数またはセキュアな保管庫を使用することをおすすめします。
• レート制限：Twitter API の不正利用を防ぐため、レート制限を実装してください。
• コンテンツの検証：悪意のある利用を防ぐため、投稿前にすべてのコンテンツを検証してください。

ライセンス

MIT