X MCP Server

🚀 X MCP Server - 增強版

這是一個為X打造的增強型模型上下文協議（MCP）服務器，在原實現基礎上增加了OAuth 2.0支持、v2 API媒體上傳功能，以及全面的速率限制。

🚀 快速開始

在開始之前，你需要完成以下準備工作：

1. 一個X開發者賬戶（可在 developer.x.com 註冊）
2. 在開發者門戶中創建一個X應用
3. API憑證（詳細設置步驟如下）
4. 安裝Node.js 18+

本服務器支持兩種認證方法，你可以根據需求進行選擇：

• OAuth 1.0a：設置更簡單，適用於所有功能，包括v1.1回退機制
• OAuth 2.0：現代認證方式，部分新功能需要使用該方式

安裝步驟

對於Claude桌面版

1. 通過NPM安裝（推薦）： 編輯Claude桌面版配置文件：
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json 添加以下配置：

   {
     "mcpServers": {
       "twitter-mcp": {
         "command": "npx",
         "args": ["-y", "@mbelinky/x-mcp-server"],
         "env": {
           "API_KEY": "your_api_key_here",
           "API_SECRET_KEY": "your_api_secret_key_here",
           "ACCESS_TOKEN": "your_access_token_here",
           "ACCESS_TOKEN_SECRET": "your_access_token_secret_here"
         }
       }
     }
   }
   

   若使用OAuth 2.0：

   {
     "mcpServers": {
       "twitter-mcp": {
         "command": "npx",
         "args": ["-y", "@mbelinky/x-mcp-server"],
         "env": {
           "AUTH_TYPE": "oauth2",
           "OAUTH2_CLIENT_ID": "your_client_id",
           "OAUTH2_CLIENT_SECRET": "your_client_secret",
           "OAUTH2_ACCESS_TOKEN": "your_access_token",
           "OAUTH2_REFRESH_TOKEN": "your_refresh_token"
         }
       }
     }
   }
   

2. 從源代碼安裝：

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

   然後更新配置文件，指向本地安裝路徑：

   {
     "mcpServers": {
       "twitter-mcp": {
         "command": "node",
         "args": ["/path/to/twitter-mcp/build/index.js"],
         "env": {
           // ... 你的憑證
         }
       }
     }
   }
   

3. 重啟Claude桌面版

對於Claude代碼版（CLI）

全局安裝服務器並添加到Claude：

# 對於OAuth 1.0a
claude mcp add twitter-mcp "npx" "-y" "@mbelinky/x-mcp-server" --scope user \
  --env "API_KEY=your_api_key" \
  --env "API_SECRET_KEY=your_secret_key" \
  --env "ACCESS_TOKEN=your_access_token" \
  --env "ACCESS_TOKEN_SECRET=your_access_token_secret"

# 對於OAuth 2.0
claude mcp add twitter-mcp "npx" "-y" "@mbelinky/x-mcp-server" --scope user \
  --env "AUTH_TYPE=oauth2" \
  --env "OAUTH2_CLIENT_ID=your_client_id" \
  --env "OAUTH2_CLIENT_SECRET=your_client_secret" \
  --env "OAUTH2_ACCESS_TOKEN=your_access_token" \
  --env "OAUTH2_REFRESH_TOKEN=your_refresh_token"

✨ 主要特性

• 發佈推文：創建文本推文，並可選擇附帶媒體（圖片、GIF）
• 搜索推文：在X上搜索推文，可自定義結果數量
• 刪除推文：以編程方式刪除你的推文
• 雙重認證：支持OAuth 1.0a和OAuth 2.0兩種認證方式
• 媒體上傳：根據每種認證方法使用相應的API版本上傳圖片
• 速率限制：內置保護機制，遵守X的API速率限制
• 類型安全：完全使用TypeScript實現，並使用Zod進行驗證

🔄 API版本處理

本服務器會根據認證方法和操作智能使用不同的X API版本：

OAuth 1.0a

• 推文操作：使用v2 API端點
• 媒體上傳：使用v1.1端點 (upload.twitter.com)
• 刪除回退：當v2失敗時，自動回退到v1.1

OAuth 2.0

• 所有操作：僅使用v2 API端點
• 媒體上傳：使用v2端點 (api.x.com/2/media/upload)
• 無v1.1訪問權限：由於認證限制，無法回退到v1.1

為什麼使用不同的端點？

• v1.1：舊版API，正在逐步淘汰，但仍可與OAuth 1.0a配合使用
• v2：現代API，功能更強大，但部分端點存在問題
• 媒體：OAuth 2.0令牌無法訪問v1.1媒體端點，必須使用v2
• 刪除：v2刪除端點目前存在問題（500錯誤），v1.1可作為回退方案

🔐 認證設置

本服務器支持兩種認證方法，你可以根據需求進行選擇：

OAuth 1.0a設置

1. 獲取憑證： 在應用的“Keys and tokens”標籤中，複製API Key和API Key Secret，生成Access Token和Secret（點擊“Generate”），確保訪問令牌具有“Read and Write”權限。
2. 所需憑證：

   API_KEY=your_api_key_here
   API_SECRET_KEY=your_api_secret_key_here
   ACCESS_TOKEN=your_access_token_here
   ACCESS_TOKEN_SECRET=your_access_token_secret_here
   

OAuth 2.0設置

1. 獲取客戶端憑證： 在應用的“Keys and tokens”標籤中，找到OAuth 2.0 Client ID和Client Secret，並保存用於下一步。
2. 生成用戶令牌： 選項A - 使用輔助腳本：

   # 首先克隆此倉庫
   git clone https://github.com/mbelinky/x-mcp-server.git
   cd x-mcp-server/twitter-mcp
   npm install
   
   # 運行OAuth2設置腳本
   node scripts/oauth2-setup.js
   

   選項B - 手動設置： 使用帶有PKCE的OAuth 2.0流程，所需範圍：tweet.read, tweet.write, users.read, media.write, offline.access，用授權碼交換訪問令牌。
3. 所需憑證：

   AUTH_TYPE=oauth2
   OAUTH2_CLIENT_ID=your_client_id_here
   OAUTH2_CLIENT_SECRET=your_client_secret_here
   OAUTH2_ACCESS_TOKEN=your_access_token_here
   OAUTH2_REFRESH_TOKEN=your_refresh_token_here
   

💻 使用示例

基礎用法

安裝完成後，Claude可以使用以下工具：

post_tweet

發佈新推文，可選擇附帶媒體和回覆。 示例提示：

• "Post a tweet saying 'Hello from Claude!'"
• "Tweet this image with the caption 'Check out this view!'"（附帶圖片）
• "Reply to tweet ID 123456789 with 'Great point!'"

search_tweets

搜索推文，可自定義結果數量（10 - 100）。 示例提示：

• "Search for tweets about #MachineLearning"
• "Find 50 recent tweets mentioning @ClaudeAI"
• "Search for tweets about TypeScript tutorials"

delete_tweet

根據推文ID刪除推文。 示例提示：

• "Delete tweet with ID 1234567890"
• "Remove my last tweet (provide the ID)"

高級用法

📸 媒體上傳注意事項

當使用Claude發佈附帶圖片的推文時：

• 使用文件路徑：將圖片保存到磁盤並提供文件路徑
• Base64限制：雖然服務器支持Base64編碼的圖片，但Claude無法從粘貼的圖片中提取Base64
• 其他客戶端：Base64支持仍可用於編程使用和其他MCP客戶端

示例用法：

# ✅ 推薦用於Claude
"Post tweet with image at /Users/me/photos/sunset.png"

# ❌ Claude目前不支持
"Post this image: [pasting an image directly]"

# ✅ 編程方式可用
// 在代碼中，你仍然可以使用Base64
{
  "text": "Hello world!",
  "media": [{
    "data": "iVBORw0KGgoAAAANS...",
    "media_type": "image/png"
  }]
}

🧪 測試

項目包含全面的測試：

# 運行所有測試
npm test

# 運行特定測試套件
npm test -- --testNamePattern="OAuth"
npm test -- --testPathPattern="unit"

🔧 技術細節

開發設置

git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install

命令

npm run build    # 構建TypeScript
npm run dev      # 在開發模式下運行
npm test         # 運行測試
npm run lint     # 代碼檢查
npm run format   # 格式化代碼

環境變量

創建一個.env文件用於本地開發：

# OAuth 1.0a
API_KEY=your_api_key
API_SECRET_KEY=your_api_secret_key
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret

# OAuth 2.0（如果使用）
AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your_client_id
OAUTH2_CLIENT_SECRET=your_client_secret
OAUTH2_ACCESS_TOKEN=your_access_token
OAUTH2_REFRESH_TOKEN=your_refresh_token

# 可選
DEBUG=true  # 啟用調試日誌

✅ OAuth 2.0媒體上傳支持

現在OAuth 1.0a和OAuth 2.0都支持媒體上傳！

• OAuth 1.0a使用v1.1媒體上傳端點 ✓
• OAuth 2.0使用v2媒體上傳端點 ✓
• 兩種認證方法都支持發佈附帶圖片（JPEG、PNG、GIF）的推文

注意：OAuth 2.0進行媒體上傳需要media.write範圍。

⚠️ 已知問題

推文刪除（臨時問題）

Twitter的v2刪除端點目前存在問題（返回500錯誤）。MCP服務器會優雅地處理此問題：

• OAuth 1.0a：自動回退到v1.1刪除端點 ✅
• OAuth 2.0：無法使用v1.1端點，將顯示有用的錯誤消息 ⚠️

這是Twitter API的臨時問題。問題解決後，兩種認證方法都將使用v2刪除功能。

🐛 故障排除

常見問題

"Could not authenticate you"

• 驗證所有憑證是否正確
• 檢查你的應用是否具有“Read and Write”權限
• 對於OAuth 1.0a，重新生成訪問令牌
• 對於OAuth 2.0，確保令牌具有所需的範圍

"Rate limit exceeded"

• Twitter有嚴格的速率限制（特別是免費層）
• 等待15分鐘後再試
• 考慮升級你的Twitter API訪問級別

"Media upload failed"

• 檢查文件大小（圖片最大5MB）
• 驗證文件格式（僅支持JPEG、PNG、GIF）
• 對於OAuth 2.0，確保包含media.write範圍

"403 Forbidden"

• 你的應用可能缺少所需的權限
• 檢查你的Twitter開發者門戶設置
• 確保你的訪問級別支持該操作

調試模式

通過設置DEBUG環境變量啟用詳細日誌記錄：

{
  "env": {
    "DEBUG": "true",
    // ... 其他憑證
  }
}

日誌位置

• Windows：%APPDATA%\Claude\logs\mcp-server-twitter.log
• macOS：~/Library/Logs/Claude/mcp-server-twitter.log

📚 資源

• Twitter API文檔
• MCP文檔
• OAuth 2.0設置指南

🤝 貢獻

歡迎貢獻代碼！請按照以下步驟進行：

1. 分叉倉庫
2. 創建功能分支
3. 為新功能添加測試
4. 確保所有測試通過
5. 提交拉取請求

🔒 隱私政策

本MCP服務器：

• 不存儲任何用戶數據：所有Twitter/X API憑證都存儲在你的本地機器上
• 不記錄敏感信息：API密鑰和令牌永遠不會被記錄
• 僅與Twitter/X通信：不會將數據發送到任何第三方服務
• 本地處理數據：所有操作都在你的機器上進行
• 遵守速率限制：內置保護機制，遵守Twitter的API速率限制

你的推文、搜索和媒體在你和Twitter/X之間保持私密。

📧 支持

• 電子郵件：mbelinky@gmail.com
• 問題反饋：GitHub Issues
• 文檔：GitHub Wiki

對於安全漏洞，請直接發送電子郵件，而不是創建公開問題。

📄 許可證

MIT

🙏 致謝

這是 @enescinar/twitter-mcp 的增強版分支，增加了以下功能：

• OAuth 2.0認證支持
• 支持OAuth 2.0的Twitter/X API v2媒體上傳
• OAuth 1.0a的自動v1.1回退機制
• 免費層的全面速率限制
• 增強的錯誤處理和調試功能
• 編程方式的OAuth 2.0令牌生成腳本

原始實現由 @enescinar 完成。