X Mcp

X(Twitter) MCP サーバー

英語 | 中国語

Claude code と Gemini CLI のチャットを通じて、X/Twitter の投稿を直接作成、管理、公開する MCP サーバーです。

注記： このプロジェクトは vidhupv/x-mcp を改変したもので、ツイートへの返信機能を追加しています。

機能

🔐 2 種類の認証方式に対応

• ✅ OAuth 1.0a：書き込み操作（ツイートの投稿、リツイートなど）用
• ✅ OAuth 2.0：読み取り操作（ツイートの取得、検索など）用
• ✅ クライアントの自動選択：システムが最適な認証方式を自動的に選択します
• ✅ スマートなフォールバック：OAuth 2.0 を利用できない場合、OAuth 1.0a に自動的に切り替えます

📝 ツイート管理

• ✅ 下書きツイートを作成
• ✅ 下書きのツイートスレッドを作成
• ✅ 既存のツイートへの返信を下書きとして作成
• ✅ すべての下書きを一覧表示
• ✅ 下書きを公開（ツイート、スレッド、返信）
• ✅ 下書きを作成せずにツイートへ直接返信
• ✅ 既存のツイートをリツイート
• ✅ コメント付きの引用ツイート
• ✅ 下書きの引用ツイートを作成
• ✅ 下書きを削除
• ✅ 失敗した下書きを自動削除（設定可能）
• ✅ 公開に失敗した場合も下書きを保持（設定可能）

⏰ ツイートの予約投稿（新機能！）

• ✅ 単一ツイートの予約 - 指定した時刻にツイートを公開
• ✅ ツイートスレッドの予約 - 指定した時刻にスレッド全体を公開
• ✅ 定期ツイート - 一定の間隔でツイートを公開
• ✅ 柔軟な時刻形式 - 絶対時刻（2024-01-15T14:30:00）と相対時刻（+10m、+2h、+1d）に対応
• ✅ バックグラウンドスケジューラー - 手動操作なしで自動実行
• ✅ 予約管理 - 予約済みツイートをすべて表示、キャンセル、管理
• ✅ スマートな間隔設定 - 定期的なコンテンツ公開やキャンペーンに最適

📷 メディア対応

• ✅ メディアファイル（画像、動画、GIF）をアップロード
• ✅ メディアを添付したツイートを作成
• ✅ アクセシビリティのための代替テキストを追加
• ✅ メディアファイルの情報を取得

📖 ツイートの取得（強化）

• ✅ ツイートの内容と情報を取得（2 種類の認証方式に対応）
• ✅ 最近のツイートを検索（エラー処理を改善）
• ✅ 複数のツイートを一括取得（接続の安定性を向上）
• ✅ 詳細なエラー診断と提案
• ✅ API 接続テストツール

システム要件

インストールを開始する前に、お使いのシステムが以下の要件を満たしていることを確認してください。

必要なソフトウェア

• Python 3.8+ - プロジェクトのランタイム環境
• Node.js 16+ - Gemini CLI のインストールに使用（Gemini を利用する場合）
• UV - Python パッケージマネージャー（推奨）または pip
• Git - プロジェクトのクローンに使用

前提条件のインストール

macOS ユーザー：

# Install Homebrew (if you don't have it)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required software
brew install python node git uv

Windows ユーザー：

# Using Chocolatey (recommended)
choco install python nodejs git

# Then install UV
pip install uv

Linux ユーザー：

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip nodejs npm git
pip3 install uv

# CentOS/RHEL
sudo yum install python3 python3-pip nodejs npm git
pip3 install uv

クイックセットアップ

Smithery 経由でのインストール

Smithery 経由で Claude code 用の X(Twitter) MCP サーバーを自動的にインストールするには：

npx -y @smithery/cli install x-mcp --client claude

Claude code 用の手動インストール

1. プロジェクトのセットアップ

プロジェクトをクローンして環境をセットアップ：

# Clone the repository
git clone https://github.com/yourusername/x-mcp.git
cd x-mcp

# Install UV (Python package manager)
# macOS users (recommended):
brew install uv

# Or use pip:
pip install uv

依存関係をインストール（いずれかの方法を選択）：

方法 1：環境の自動作成とインストール（推奨）

# One step: create virtual environment and install dependencies
uv sync

# Activate virtual environment (if manual operation needed)
# macOS/Linux:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

方法 2：環境の手動作成とインストール

# Manually create virtual environment
uv venv

# Activate virtual environment
# macOS/Linux:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

# Install dependencies from pyproject.toml
uv pip sync pyproject.toml

2. Claude Desktop の設定

claude_desktop_config.json を作成：

• MacOS の場合： ディレクトリ ~/Library/Application Support/Claude/ を開き、その中にファイルを作成します
• Windows の場合： ディレクトリ %APPDATA%/Claude/ を開き、その中にファイルを作成します

以下の設定を claude_desktop_config.json に追加：

基本設定（OAuth 1.0a のみ）

{
  "mcpServers": {
    "x_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-mcp",
        "run",
        "x-mcp"
      ],
      "env": {
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

推奨構成（OAuth 1.0a + OAuth 2.0 のデュアル認証）

{
  "mcpServers": {
    "x_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-mcp",
        "run",
        "x-mcp"
      ],
      "env": {
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "TWITTER_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

💡 デュアル認証構成の使用をおすすめします：TWITTER_BEARER_TOKEN を追加すると、ツイート取得機能の安定性と成功率を大幅に向上できます。

3. X/Twitter API の認証情報を取得する

1. X API Developer Portal にアクセスする：

   • X API Developer Portal にアクセスします
   • 開発者アカウントを作成します（まだお持ちでない場合）

2. プロジェクトとアプリを作成する：

   • 新しいプロジェクトを作成します
   • プロジェクト内にアプリを作成します

3. アプリの権限を設定する：

   • User Authentication Settings で、Read and Write permissions に設定します
   • アプリの種類：Web App を選択します
   • Callback URL：http://localhost/ に設定します
   • Website URL：http://example.com/ に設定します

4. API キーとトークンを生成する：

   • 「Keys and Tokens」セクションで、次の情報を生成します：
     • API Key（Consumer Key）
     • API Secret（Consumer Secret）
     • Access Token
     • Access Token Secret
     • Bearer Token（デュアル認証におすすめ）

4. 構成を更新して起動する

構成ファイルを更新します：

• /path/to/x-mcp を実際のプロジェクトパス（例：/Users/yourname/x-mcp）に置き換えます
• すべての your_* プレースホルダーを実際の API 認証情報に置き換えます

Claude を完全に終了してから、再度開きます

5. インストールを確認する

Claude で接続をテストします：

test api connection

正しく構成されていれば、接続テストが成功したことを示す結果が表示されます。

Gemini CLI の構成

Claude code の代わりに、この MCP サーバーを Gemini CLI で使用する場合：

1. プロジェクトをセットアップする

プロジェクトをクローンして環境をセットアップします：

# Clone the repository
git clone https://github.com/yourusername/x-mcp.git
cd x-mcp

# Install UV (Python package manager)
# macOS users:
brew install uv

# Or use pip:
pip install uv

依存関係をインストールします（いずれかの方法を選択してください）：

方法 1：環境の自動作成とインストール（推奨）

# One step: create virtual environment and install dependencies
uv sync

# Activate virtual environment (if manual operation needed)
# macOS/Linux:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

方法 2：環境の手動作成とインストール

# Manually create virtual environment
uv venv

# Activate virtual environment
# macOS/Linux:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

# Install dependencies from pyproject.toml
uv pip sync pyproject.toml

2. Gemini CLI をインストールして構成する

Gemini CLI をインストールします：

npm install -g @google/gemini-cli

MCP 構成ファイルを作成または更新します：

# Create configuration directory (if it doesn't exist)
mkdir -p ~/.gemini

# Create configuration file
touch ~/.gemini/settings.json

構成ファイル ~/.gemini/settings.json を編集します：

基本構成（OAuth 1.0a のみ）

{
  "mcpServers": {
    "x_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-mcp",
        "run",
        "x-mcp"
      ],
      "env": {
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

推奨構成（OAuth 1.0a + OAuth 2.0 のデュアル認証）

{
  "mcpServers": {
    "x_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-mcp",
        "run",
        "x-mcp"
      ],
      "env": {
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "TWITTER_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

3. X/Twitter API の認証情報を取得する

1. X API Developer Portal にアクセスする：

   • X API Developer Portal にアクセスします
   • 開発者アカウントを作成します（まだお持ちでない場合）

2. プロジェクトとアプリを作成する：

   • 新しいプロジェクトを作成します
   • プロジェクト内にアプリを作成します

3. アプリの権限を設定する：

   • User Authentication Settings で、Read and Write permissions に設定します
   • アプリの種類：Web App を選択します
   • Callback URL：http://localhost/ に設定します
   • Website URL：http://example.com/ に設定します

4. API キーとトークンを生成する：

   • 「Keys and Tokens」セクションで、次の情報を生成します：
     • API Key（Consumer Key）
     • API Secret（Consumer Secret）
     • Access Token
     • Access Token Secret
     • Bearer Token（デュアル認証におすすめ）

4. 構成を更新して起動する

構成ファイルを更新します：

• /path/to/x-mcp を実際のプロジェクトパス（例：/Users/yourname/x-mcp）に置き換えます
• すべての your_* プレースホルダーを実際の API 認証情報に置き換えます

Gemini CLI を起動します：

# Start Gemini CLI with MCP support
gemini-cli

# Or if you need to specify config file path:
gemini-cli --config ~/.gemini/settings.json

5. インストールを確認する

Gemini CLI で接続をテストします：

test api connection

正しく構成されていれば、接続テストが成功したことを示す結果が表示されます。

高度な構成

失敗した下書きを自動削除する

ツイートの公開に失敗した場合、下書きを自動削除するかどうかを選択できます：

• 自動削除を有効にする（デフォルト）：無効な下書きが蓄積しないよう、公開に失敗したときに下書きを自動削除します
• 自動削除を無効にする：公開に失敗したときも下書きを保持し、手動での再試行や編集を可能にします

設定方法

1. 環境変数を使用：設定ファイルに "AUTO_DELETE_FAILED_DRAFTS": "true" または "false" を追加します
2. コマンドを使用：「失敗した下書きの自動削除を有効にする」または「失敗した下書きの自動削除を無効にする」を使用します
3. ステータスを確認：「現在の自動削除設定を確認」を使用します

使用例

Claude code と Gemini CLI の両方で動作します：

基本的なツイート操作

• 「『AI を使ってツイートする方法を覚えたばかりです。驚きました！🤖✨』とツイート」
• 「ピザの歴史についてスレッドを作成」
• 「下書きのツイートを表示」
• 「この下書きを公開！」
• 「その下書きを削除」
• 「ツイート 1234567890 に『素晴らしい指摘ですね！共有ありがとうございます。』と返信」
• 「ツイート 1234567890 に『この視点に完全に同意します。』と下書き返信を作成」
• 「ツイート 1234567890 をリツイート」
• 「ツイート 1234567890 を『まさに私が考えていたことです！』というコメント付きで引用ツイート」
• 「1234567890 に『ここには素晴らしい洞察があります』というコメント付きで下書き引用ツイートを作成」

メディア操作

• 「画像 /path/to/image.jpg を、代替テキスト『山々に沈む美しい夕日』付きでアップロード」
• 「メディア ID 123456789 を使って『この素晴らしい写真を見てください！』というメディア付きツイートを作成」
• 「動画 /path/to/video.mp4 を添付して、『最新のプロジェクト』というメディア付き下書きツイートを作成」

予約ツイート（新機能！）

• 「『皆さん、おはようございます！☀️』というツイートを明日の午前 9 時に予約」
• 「生産性向上のヒントについて、来週月曜日の午後 2 時に投稿する予約スレッドを作成」
• 「5 分後に開始し、10 分ごとに繰り返すツイートを設定：['ヒント 1：水分補給を忘れずに', 'ヒント 2：休憩を取る', 'ヒント 3：定期的に運動する']」
• 「『週末気分！🎉』というツイートを +2h に予約」
• 「やる気が出る名言を使ったツイートを、次の 3 時間、30 分ごとに繰り返すよう作成」
• 「予約済みのツイートをすべて一覧表示」
• 「予約済みツイート scheduled_tweet_1234567890.json をキャンセル」
• 「ツイートスケジューラーを開始」
• 「ツイートスケジューラーを停止」

設定と管理

• 「失敗した下書きの自動削除を有効にする」
• 「失敗した下書きの自動削除を無効にする」
• 「現在の自動削除設定を確認」

ツイートの取得

• 「ツイート 1234567890 の内容と情報を取得」
• 「過去 7 日間の『AI OR artificial intelligence』を含むツイートを検索」
• 「ツイート 123456789、987654321、555666777 の情報を取得」

トラブルシューティング

環境設定の問題

UV が見つからない、またはインストールに失敗した場合：

# Check if UV is properly installed
which uv
uv --version

# If not found, reinstall
pip uninstall uv
brew install uv  # macOS
# or
pip install uv   # other systems

仮想環境の問題：

# Delete existing virtual environment
rm -rf .venv

# Recreate (choose one method):

# Method 1: Automatic creation and installation (recommended)
uv sync

# Method 2: Manual creation and installation
uv venv
source .venv/bin/activate  # macOS/Linux or .venv\Scripts\activate (Windows)
uv pip sync pyproject.toml

Python バージョンの互換性の問題：

# Check Python version (requires 3.8+)
python --version
python3 --version

# If version is too old, upgrade Python
brew install [email protected]  # macOS
# or use your system package manager to upgrade

基本的な問題

動作しない場合：

• UV がグローバルにインストールされていることを確認します（インストールされていない場合は、pip uninstall uv でアンインストールし、brew install uv で再インストールします）
• または、which uv で UV のパスを確認し、"command": "uv" をフルパスに置き換えます
• X/Twitter の認証情報がすべて正しいことを確認します
• 設定内の x-mcp のパスが、実際のリポジトリの場所と一致することを確認します

🔧 API 接続のテスト

簡易診断：

test api connection

Claude でこのコマンドを実行すると、次のことを行います：

• OAuth 1.0a と OAuth 2.0 の接続をテストします
• API の権限と制限を確認します
• 詳細な診断情報と提案を提示します

テストスクリプトを実行：

cd /path/to/x-mcp
python test_tweet_functions.py

🚨 401 Unauthorized エラーの修正

問題の症状：

• ツイートの投稿時に「401 Unauthorized」エラーが発生する
• ツイートは投稿できるが、取得できない

解決方法：

1. Bearer Token を追加（推奨）：

   "env": {
     "TWITTER_API_KEY": "your_api_key",
     "TWITTER_API_SECRET": "your_api_secret",
     "TWITTER_ACCESS_TOKEN": "your_access_token",
     "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret",
     "TWITTER_BEARER_TOKEN": "your_bearer_token"
   }
   

2. API 認証情報を再生成：

   • Twitter Developer Portal にアクセスします
   • すべての API キーとトークンを再生成します
   • 権限が「Read and write」に設定されていることを確認します

3. プロジェクト設定を確認：

   • ユーザー認証設定：読み取りおよび書き込み権限
   • アプリの種類：Web アプリ
   • コールバック URL：http://localhost/
   • ウェブサイト URL：http://example.com/

📖 ツイート取得時の問題

デュアル認証のメリット：

• 読み取り操作には OAuth 2.0 を使用（より安定）
• 書き込み操作には OAuth 1.0a を使用（必須）
• 自動フォールバックに対応

よくあるエラーと解決方法：

エラーコード	原因	解決方法
401	認証に失敗しました	API 認証情報を確認し、トークンを再生成します
403	権限が不足しています	API プランをアップグレードするか、権限設定を確認します
404	ツイートが見つかりません	ツイート ID を確認し、ツイートが公開されているか確認します
429	レート制限を超過しました	15 分待つか、API プランをアップグレードします

API プランの制限：

• 無料ユーザー：制限付きの基本機能
• Basic（$100/月）：すべての読み取り機能
• Pro（$5000/月）：高度な機能とより高い上限

🔍 詳細な診断手順

1. 認証状態を確認：

   test api connection
   

2. 設定を確認：

   • すべての環境変数が設定されていることを確認します
   • パスが正しいことを確認します
   • API キーの形式を検証します

3. 特定の機能をテスト：

   search for tweets containing "hello"
   get tweet 1234567890 content
   

4. 詳細ログを確認：

   • Claude Desktop のコンソールを確認します
   • MCP サーバーのログを確認します
   • 具体的なエラーメッセージを記録します

クレジット

このプロジェクトは、Vidhu Panhavoor Vasudevan 氏による、元の x-mcp リポジトリの優れた成果を基にしています。

このフォークでの新機能

• 🆕 予約ツイートシステム - 柔軟なタイミングで、単一のツイート、スレッド、定期ツイートを予約できます
• 🆕 OAuth デュアル認証システム - OAuth 1.0a と OAuth 2.0 に対応し、最適な認証方法を自動選択します
• 🆕 401 エラーの修正 - ツイート取得時の認証問題を解決しました
• 🆕 スマートなクライアント選択 - 読み取り操作では OAuth 2.0 を優先し、書き込み操作では OAuth 1.0a を使用します
• 🆕 強化されたエラー処理 - 詳細なエラー診断と英語のエラーメッセージに対応しました
• 🆕 API 接続テストツール - 接続テストと診断機能を内蔵しています
• ✅ ツイートへの返信機能 - 返信の下書きを作成し、既存のツイートに直接返信できます
• ✅ リツイート機能 - シンプルなリツイートや、コメント付きの引用ツイートに対応しています
• ✅ メディア機能 - 代替テキストに対応し、画像、動画、GIF をアップロードできます
• ✅ ツイート取得機能 - ツイートの内容取得、ツイートの検索、複数ツイートの一括取得ができます
• ✅ 下書き管理の強化 - 公開に失敗した際の下書き保持を改善し、すべての種類の下書きに対応しました

この MCP サーバーの基盤を作成してくださった原作者に、特に感謝いたします！

詳細なドキュメント

より詳しい機能の説明と使用ガイドについては、以下を参照してください。

• 予約ツイート機能 - 🆕 予約ツイート機能の完全ガイド
• 定时发推文功能说明 - 🆕 予約ツイートガイドの中国語版
• OAuth Dual Authentication Setup Guide - 🆕 デュアル認証の詳細な設定ガイド
• OAuth双重认证配置指南 - 設定ガイドの中国語版
• 推文获取功能故障排除指南 - 中国語のトラブルシューティングガイド
• REPLY_FUNCTIONALITY.md - 返信機能の詳細なドキュメント