X/Twitter MCP Server

X/Twitter MCP サーバー

Playwright を使用したブラウザー自動化を通じて、非公式の X/Twitter API アクセスを提供する Model Context Protocol（MCP）サーバーです。このサーバーにより、AI エージェントやアプリケーションはコンテンツの作成、スクレイピング、ソーシャルメディアの自動化を目的として、プログラムから X/Twitter を操作できます。

🚀 機能

コンテンツの作成と操作

• ツイートとスレッドの投稿：メディアに対応した単一のツイート、または複数のツイートからなるスレッドを投稿します
• 投稿への操作：投稿への「いいね」、いいねの取り消し、リツイート、リツイートの取り消し、ブックマーク、引用ツイート、返信を行います
• コメント管理：コメントへの「いいね」、いいねの取り消し、返信、編集を行います
• メディア対応：画像、動画、GIF をアップロードしてツイートに添付します

コンテンツのスクレイピングと分析

• タイムラインのスクレイピング：「おすすめ」と「フォロー中」のタイムラインから投稿を抽出します
• プロフィールのスクレイピング：包括的なユーザープロフィールデータと最近の投稿を取得します
• 検索機能：バズったコンテンツ、特定のユーザー、期間を対象としたフィルター付きの高度な検索を行います
• コメントのスクレイピング：特定の投稿からコメントと返信を抽出します
• トレンドトピック：現在のトレンドトピックとハッシュタグを取得します

MCP 連携

• デュアルトランスポート対応：stdio と HTTP/SSE の両方のトランスポートで動作します
• ツールベースのインターフェース：AI エージェントが X/Twitter を操作するための 20 個以上のツールを利用できます
• 構造化された応答：包括的なメタデータを含む JSON 形式の応答を返します
• エラー処理：説明的なエラーメッセージを備えた堅牢なエラー処理を行います

📋 前提条件

• Node.js 18+
• 有効な X/Twitter アカウントの認証情報
• Docker（任意。コンテナ化してデプロイする場合）

クイックスタート

1. この設定を Claude Desktop の設定ファイルに追加します。

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

{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@barresider/x-mcp"],
      "env": {
        "TWITTER_USERNAME": "your_twitter_username",
        "TWITTER_PASSWORD": "your_twitter_password"
      }
    }
  }
}

プロキシを使用する場合（任意）：

{
  "mcpServers": {
    "x-mcp": {
      "command": "npx",
      "args": ["-y", "@barresider/x-mcp"],
      "env": {
        "TWITTER_USERNAME": "your_twitter_username",
        "TWITTER_PASSWORD": "your_twitter_password",
        "PROXY_URL": "http://proxy-server:port"
      }
    }
  }
}

2. Claude Desktop を再起動します

これで完了です！Claude は、次のような 25 個以上の強力なツールを通じて X/Twitter を操作できるようになります。

• tweet：任意のメディアを添付して新しいツイートを投稿します
• thread：複数のツイートからなるスレッドを投稿します
• search_twitter：高度なフィルターを使ってツイートを検索します
• scrape_profile：包括的なユーザープロフィールデータを取得します
• scrape_timeline：タイムラインから投稿を抽出します
• like_post、retweet_post、bookmark_post：投稿を操作します
• その他、X/Twitter を包括的に自動化するためのさまざまなツール

使用例

Claude に次のように尋ねてみてください。

• 「『Hello from Claude!』というツイートを投稿してくれますか？」
• 「Claude AI についてのツイートを検索してくれますか？」
• 「Elon Musk のプロフィールをスクレイピングして、最新のツイートを 5 件表示してくれますか？」
• 「AI のメリットについてのスレッドを投稿してくれますか？」

🛠️ インストール

ローカル開発環境へのインストール

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

git clone <repository-url>
cd x-mcp

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

npm install

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

npm run build

Docker でのインストール

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

docker build -t x-mcp .

2. または、Docker Compose を使用します。

docker-compose --profile mcp up --build

⚙️ 設定

環境変数

プロジェクトのルートに .env ファイルを作成します。

# Required: X/Twitter credentials
TWITTER_USERNAME=your_username
TWITTER_PASSWORD=your_password

# Optional: Proxy configuration
PROXY_URL=http://proxy-server:port          # Full proxy URL (supports http/https)
# or with authentication
PROXY_URL=http://username:password@proxy-server:port
# or separately
PROXY_URL=http://proxy-server:port
PROXY_USERNAME=proxy_username               # Optional: separate username
PROXY_PASSWORD=proxy_password               # Optional: separate password

# Optional: MCP server configuration
MCP_TRANSPORT=stdio           # Options: stdio, sse, http
MCP_PORT=3000                # Port for HTTP/SSE transport

# Optional: Directory for authentication state (default: playwright/.auth)
AUTH_DIR=playwright/.auth

認証の設定

1. 認証ディレクトリを作成するか、AUTH_DIR 環境変数を設定します（任意）。

export AUTH_DIR=/path/to/auth/dir
mkdir -p "${AUTH_DIR:-playwright/.auth}"

2. X/Twitter にログインします（セッションが保存され、再利用されます）。

npm run cli login
# or
node dist/cli.js login

🔧 利用可能な MCP ツール

このサーバーは、X/Twitter を包括的に操作するための 25 個以上のツールを提供します。

認証とセットアップ

• login - X/Twitter で認証します

コンテンツの作成

• tweet - 任意のメディアを添付して単一のツイートを投稿します
• thread - 複数のツイートからなるスレッドを投稿します
• reply_to_post - 特定の投稿に返信します
• quote_tweet - 追加テキストを添えて引用ツイートします

投稿への操作

• like_post / unlike_post - 投稿への「いいね」と取り消しを行います
• retweet_post / unretweet_post - 投稿のリツイートと取り消しを行います
• bookmark_post / unbookmark_post - ブックマークを管理します

コメントへの操作

• like_comment_by_id / unlike_comment_by_id - コメントへの「いいね」と取り消しを行います
• reply_to_comment_by_id - コメントに返信します
• replace_comment_by_id - コメントを編集します（対応している場合）

コンテンツのスクレイピング

• scrape_posts - 現在のページから投稿をスクレイピングします
• scrape_profile - ユーザープロフィールと最近の投稿を取得します
• scrape_comments - 投稿からコメントを抽出します
• scrape_timeline - 「おすすめ」／「フォロー中」のタイムラインをスクレイピングします
• scrape_trending - トレンドトピックを取得します
• search_twitter - 一般的な検索機能
• search_viral - エンゲージメントの最低条件を満たすバイラルコンテンツを検索します

📊 データ構造

TwitterPost

interface TwitterPost {
  postId: string;
  author: TwitterUser;
  content: string;
  timestamp: Date;
  media: TwitterMedia[];
  metrics: PostMetrics;
  engagementRate: number;
  isRetweet?: boolean;
  retweetedFrom?: TwitterUser;
  quotedPost?: TwitterPost;
  url: string;
}

TwitterProfile

interface TwitterProfile extends TwitterUser {
  bannerUrl?: string;
  bio?: string;
  location?: string;
  website?: string;
  joinedDate?: Date;
  followingCount: number;
  followersCount: number;
  postsCount: number;
  isFollowing?: boolean;
  isFollowedBy?: boolean;
  latestPosts?: TwitterPost[];
}

PostMetrics

interface PostMetrics {
  likesCount: number;
  retweetsCount: number;
  quotesCount: number;
  repliesCount: number;
  impressionsCount: number;
  bookmarksCount: number;
}

🔒 セキュリティとベストプラクティス

レート制限

• レート制限を回避するため、リクエストの間に遅延を設けます
• スクレイピング操作では妥当な上限を設定します
• レート制限の応答がないか監視します

認証

• 認証情報は環境変数に安全に保存します
• セッションデータは、AUTH_DIR 環境変数で指定されたディレクトリに保存されます（デフォルトは playwright/.auth/ です）
• 定期的な再認証が必要になる場合があります

エラー処理

• すべての操作に包括的なエラー処理が含まれます
• トラブルシューティングに役立つ、わかりやすいエラーメッセージを表示します
• 要素が見つからない場合も、適切に処理を継続します

プロキシ設定

• すべてのブラウザー接続で HTTP/HTTPS プロキシをサポートします
• PROXY_URL 環境変数で設定します
• ユーザー名／パスワードによる認証をサポートします
• 次の用途に役立ちます。
  • IP アドレスを切り替えてレート制限を回避する
  • 制限されたネットワークから X/Twitter にアクセスする
  • 匿名性をさらに高める
• 設定例：
  • 基本形式：http://proxy-server:port
  • 認証情報付き：http://username:password@proxy-server:port
  • 認証情報を別々に指定する場合：PROXY_USERNAME と PROXY_PASSWORD を使用します

🐳 Docker によるデプロイ

Docker Compose を使用する

# Start the MCP server
docker-compose --profile mcp up

# With environment variables
TWITTER_USERNAME=your_username TWITTER_PASSWORD=your_password docker-compose --profile mcp up

Docker をカスタム設定で実行する

docker run -d \
  --name x-mcp \
  -e TWITTER_USERNAME=your_username \
  -e TWITTER_PASSWORD=your_password \
  -e PROXY_URL=http://proxy-server:port \
  -e MCP_TRANSPORT=sse \
  -e MCP_PORT=3000 \
  -p 3000:3000 \
  x-mcp

🛠️ 開発

プロジェクト構成

src/
├── mcp.ts                    # Main MCP server implementation
├── cli.ts                    # Command line interface
├── types.ts                  # TypeScript type definitions
├── utils.ts                  # Utility functions
├── behaviors/                # User interaction behaviors
│   ├── login.ts             # Authentication logic
│   ├── interact-with-post.ts # Post interaction functions
│   ├── interact-with-comment.ts # Comment interaction functions
│   └── upload-media.ts      # Media upload functionality
└── scrapers/                # Data scraping modules
    ├── index.ts             # Scraper exports
    ├── post-scraper.ts      # Post scraping logic
    ├── profile-scraper.ts   # Profile scraping logic
    ├── comment-scraper.ts   # Comment scraping logic
    ├── search-scraper.ts    # Search functionality
    ├── timeline-scraper.ts  # Timeline scraping
    └── utils.ts             # Scraping utilities

ビルドとテスト

# Build TypeScript
npm run build

# Run MCP server
npm run mcp

# Run CLI commands
npm run cli <command>

🤝 コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 十分にテストします
5. プルリクエストを送信します

ガイドライン

• TypeScript のベストプラクティスに従ってください
• 包括的なエラー処理を追加してください
• 新機能に合わせて型定義を更新してください
• 実際の X/Twitter での操作を使ってテストしてください
• 新機能についてドキュメントを作成してください

⚠️ 免責事項

• これはブラウザー自動化を使用する非公式ツールです
• X/Twitter の利用規約が適用されます
• 責任を持って使用し、レート制限を遵守してください
• UI の変更により、セレクターの更新が必要になる場合があります
• X/Twitter とは無関係です

📄 ライセンス

[ライセンス情報はこちら]

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

よくある問題

認証に失敗する

• .env ファイルの認証情報を確認してください
• npm run cli login を使って再度ログインしてください
• 2FA が必要かどうか確認してください

要素が見つからないエラー

• X/Twitter の UI が更新されている可能性があります
• ブラウザーのキャッシュを消去して、再認証してください
• 要素セレクターが更新されていないか確認してください

レート制限

• リクエストの頻度を下げてください
• 操作の間に遅延を追加してください
• バッチサイズを小さくしてください

コンテナーの問題

• 環境変数が適切に設定されていることを確認してください
• ポートが使用可能か確認してください
• Docker のネットワーク設定を確認してください

さらにサポートが必要な場合は、プロジェクトのリポジトリで issue を作成してください。