X MCP

🚀 x-mcp

x-mcp 是一個 MCP（模型上下文協議）服務器，它能讓 AI 代理全面訪問 X（原 Twitter）API。通過自然語言，你可以實現發佈推文、搜索、查看時間線、點贊、轉發、上傳媒體等操作。

該項目可與 Claude Code、Claude Desktop、OpenAI Codex、Cursor、Windsurf、Cline 以及其他任何支持 MCP 的客戶端配合使用。

如果你是一個大語言模型/AI 代理，正在幫助用戶設置此項目，請閱讀 以獲取可逐步指導用戶完成設置的說明。

🚀 快速開始

🔍 功能概述

該項目支持使用推文的 URL 或 ID，你可以粘貼 https://x.com/user/status/123 或僅輸入 123。

📦 安裝指南

1. 克隆並構建項目

git clone https://github.com/INFATOSHI/x-mcp.git
cd x-mcp
npm install
npm run build

2. 獲取 X API 憑證

你需要從 X 開發者門戶 獲取 5 個憑證，以下是具體獲取步驟：

a) 創建應用

1. 訪問 X 開發者門戶。
2. 使用你的 X 賬戶登錄。
3. 點擊左側側邊欄中的 應用。
4. 點擊 創建應用（你可能需要先註冊開發者賬戶）。
5. 為應用命名（例如 my-x-mcp）。
6. 你將立即看到 消費者密鑰（API 密鑰）、密鑰（API 密鑰密鑰）和 Bearer 令牌。
7. 立即保存這三個憑證，因為密鑰不會再次顯示。

b) 啟用寫入權限

默認情況下，新應用僅具有讀取權限。若要發佈推文、點贊、轉發等操作，你需要讀取和寫入權限。

1. 在應用頁面中，向下滾動到 用戶身份驗證設置。
2. 點擊 設置。
3. 將 應用權限 設置為 讀取和寫入。
4. 將 應用類型 設置為 Web 應用、自動化應用或機器人。
5. 將 回調 URI / 重定向 URL 設置為 https://localhost（必需但不會使用）。
6. 將 網站 URL 設置為任何有效的 URL（例如 https://x.com）。
7. 點擊 保存。

c) 生成訪問令牌（具有寫入權限）

啟用寫入權限後，你需要生成（或重新生成）訪問令牌和密鑰，以便它們包含新的權限：

1. 返回應用的 密鑰和令牌 頁面。
2. 在 訪問令牌和密鑰 下，點擊 重新生成。
3. 保存 訪問令牌 和 訪問令牌密鑰。

如果你在生成令牌之前跳過了步驟 (b)，你的令牌將僅具有讀取權限，發佈操作將返回 403 錯誤。

3. 配置憑證

複製示例環境文件並填寫你的 5 個憑證：

cp .env.example .env

編輯 .env 文件：

X_API_KEY=your_consumer_key
X_API_SECRET=your_secret_key
X_BEARER_TOKEN=your_bearer_token
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret

💻 連接到客戶端

選擇以下客戶端之一進行連接，你只需遵循其中一個部分的說明。

Claude Code

claude mcp add --scope user x-twitter -- node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

將 /ABSOLUTE/PATH/TO/x-mcp 替換為你克隆倉庫的實際路徑，然後重啟 Claude Code。

Claude Desktop

將以下內容添加到你的 claude_desktop_config.json 文件中：

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

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

Cursor

將以下內容添加到你的 Cursor MCP 配置文件中：

• 全局（所有項目）：~/.cursor/mcp.json
• 項目範圍：項目根目錄下的 .cursor/mcp.json

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

你還可以在 Cursor 設置 > MCP 服務器中驗證連接。

OpenAI Codex

選項 A：命令行界面（CLI）

codex mcp add x-twitter --env X_API_KEY=your_consumer_key --env X_API_SECRET=your_secret_key --env X_ACCESS_TOKEN=your_access_token --env X_ACCESS_TOKEN_SECRET=your_access_token_secret --env X_BEARER_TOKEN=your_bearer_token -- node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

選項 B：config.toml

將以下內容添加到 ~/.codex/config.toml（全局）或 .codex/config.toml（項目範圍）中：

[mcp_servers.x-twitter]
command = "node"
args = ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"]

[mcp_servers.x-twitter.env]
X_API_KEY = "your_consumer_key"
X_API_SECRET = "your_secret_key"
X_ACCESS_TOKEN = "your_access_token"
X_ACCESS_TOKEN_SECRET = "your_access_token_secret"
X_BEARER_TOKEN = "your_bearer_token"

Windsurf

將以下內容添加到 ~/.codeium/windsurf/mcp_config.json 中：

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

你也可以從 Windsurf 設置 > 級聯 > MCP 服務器中添加。

Cline（VS Code）

打開 Cline 的 MCP 設置（點擊 Cline 頂部導航欄中的 MCP 服務器圖標 > 配置），然後將以下內容添加到 cline_mcp_settings.json 中：

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

其他 MCP 客戶端

這是一個標準的標準輸入輸出 MCP 服務器。對於任何兼容 MCP 的客戶端，請將其指向：

node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

並設置以下環境變量：X_API_KEY、X_API_SECRET、X_ACCESS_TOKEN、X_ACCESS_TOKEN_SECRET、X_BEARER_TOKEN。

📚 詳細文檔

故障排除

發佈時出現 403 "oauth1-permissions" 錯誤

你的訪問令牌是在啟用寫入權限之前生成的。請訪問 X 開發者門戶，確保應用權限設置為 "讀取和寫入"，然後 重新生成 你的訪問令牌和密鑰。

401 未授權錯誤

仔細檢查 .env 文件中的所有 5 個憑證是否正確，確保沒有額外的空格或換行符。

429 速率限制錯誤

錯誤消息會明確顯示速率限制何時重置。請等待到該時間，或減少請求頻率。

回覆時出現權限/限制錯誤

截至 2024 年 2 月，X 通過 API 限制程序化回覆。只有當原作者 @提及你或引用你的推文時，你才能進行回覆。這適用於免費、基礎、專業和按使用付費層級（企業層級除外）。你可以使用 quote_tweet 作為替代方法。

服務器顯示 "已連接" 但工具未使用

確保你以正確的範圍（用戶/全局，如果你希望在所有地方都可用，則不要使用項目範圍）添加了服務器，然後重啟客戶端。

速率限制

每個響應都包含速率限制信息：剩餘請求數、總限制和重置時間。當達到限制時，你將收到一個明確的錯誤消息，其中包含確切的重置時間戳。

分頁

列表端點在響應中返回 next_token。你可以傳遞該令牌以獲取下一頁結果。此功能適用於 search_tweets、get_timeline、get_mentions、get_followers、get_following。

搜索查詢語法

search_tweets 工具支持 X 的完整查詢語言：

• from:username -- 特定用戶發佈的推文
• to:username -- 對特定用戶的回覆
• #hashtag -- 包含特定話題標籤的推文
• "exact phrase" -- 精確文本匹配
• has:media / has:links / has:images -- 按內容類型過濾
• is:reply / -is:retweet -- 按推文類型過濾
• lang:en -- 按語言過濾
• 可以使用空格（AND）或 OR 進行組合

📄 許可證

本項目採用 MIT 許可證。