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 完成。