X (Twitter) MCP Server - Enhanced Edition

X MCP服务器-增强版

用于X的增强型模型上下文协议（MCP）服务器，为原始实现添加了OAuth 2.0支持、v2 API媒体上传和全面的速率限制。

✨ 特性

• 发布推文：创建带有可选媒体附件（图像、GIF）的文本推文
• 搜索推文：使用可自定义的结果计数搜索X
• 删除推文：以编程方式删除您的推文
• 双重身份验证：同时支持OAuth 1.0a和OAuth 2.0
• 媒体上传：为每个身份验证方法使用适当的API版本发布图像
• 速率限制：X的API限制的内置保护
• 类型安全：带Zod验证的完整TypeScript实现

🔄 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
• 第2版：现代API具有更好的功能，但某些端点存在问题
• 媒体：OAuth 2.0令牌无法访问v1.1媒体端点，必须使用v2
• 删除：v2删除终结点当前有问题（500个错误），v1.1作为回退

📋 先决条件

在开始之前，您需要：

1. X开发人员帐户（在以下网址注册 developer.x.com)
2. 在开发人员门户中创建的X应用程序
3. API凭据（详细设置如下）
4. 已安装Node.js 18+

🔐 身份验证设置

此服务器支持两种身份验证方法。根据您的需求进行选择：

• OAuth 1.0a：设置更简单，适用于包括v1.1回退在内的所有功能
• OAuth 2.0：现代身份验证，某些较新功能需要

设置您的X应用程序

1. 创建开发人员帐户:

- 首选 developer.x.com - 使用您的推特帐户登录 - 如果您还没有申请开发人员访问权限

1. 创建新应用程序:

- 导航到 Twitter开发者门户 - 点击“项目和应用程序”→ “新项目” - 为您的项目命名 - 选择您的用例 - 在项目中创建新应用程序

1. 配置应用程序权限:

- 在您的应用程序设置中，转到“用户身份验证设置” - 点击“设置” - 启用OAuth 1.0a和/或OAuth 2.0 - 将应用程序权限设置为“读写” - 添加回调URL： - 对于OAuth 1.0a： http://localhost:3000/callback - 对于OAuth 2.0： http://localhost:3000/callback - 设置网站URL（可以是您的GitHub仓库）

OAuth 1.0a设置

1. 获取您的凭据:

- 在应用程序的“密钥和令牌”选项卡中 - 复制您的API密钥和API密钥机密 - 生成访问令牌和密码（点击“生成”） - 确保访问令牌具有“读取和写入”权限

1. 所需凭据:

   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. 获取您的客户凭据:

- 在应用程序的“密钥和令牌”选项卡中 - 查找OAuth 2.0客户端ID和客户端密码 - 将这些保存到下一步

1. 生成用户令牌:

选项A-使用我们的辅助脚本：

   # Clone this repository first
   git clone https://github.com/mbelinky/x-mcp-server.git
   cd x-mcp-server/twitter-mcp
   npm install

   # Run the OAuth2 setup script
   node scripts/oauth2-setup.js

选项B-手动设置：

- 使用OAuth 2.0流和PKCE - 所需范围： tweet.read, tweet.write, users.read, media.write, offline.access - 访问令牌的交换授权码

1. 所需凭据:

   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

🚀 安装

适用于克劳德桌面

1. 通过NPM安装 （推荐）：

编辑您的Claude Desktop配置文件：

- 窗户： %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"
         }
       }
     }
   }

1. 从源代码安装:

   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": {
           // ... your credentials
         }
       }
     }
   }

1. 重新启动克劳德桌面

克劳德代码（CLI）

全局安装服务器并将其添加到Claude：

# For 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"

# For 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"

🛠️ 可用工具

安装后，Claude可以使用这些工具：

post_tweet

发布一条带有可选媒体附件和回复的新推文。

示例提示：

• “发一条推特说‘克劳德你好！’”
• “在推特上发布这张图片，标题为‘查看此视图！’”（附上图片）
• “在推特ID 123456789上回复‘说得好！’”

search_tweets

搜索具有可定制结果计数（10-100）的推文。

示例提示：

• “搜索有关#MachineLearning的推文”
• “找到50条最近提到@ClaudeAI的推文”
• “搜索有关TypeScript教程的推文”

delete_tweet

按ID删除推文。

示例提示：

• “删除ID为1234567890的推文”
• “删除我最后一条推文（提供ID）”

注意：由于Twitter API的临时问题，OAuth 1.0a使用v1.1回退进行删除。

📸 媒体上传说明

当使用Claude发布带有图片的推文时：

• 使用文件路径：将图像保存到磁盘并提供文件路径
• Base64限制：虽然服务器支持base64编码的图像，但Claude无法从粘贴的图像中提取base64
• 其他客户：Base64支持仍然可用于编程用途和其他MCP客户端

示例用法：

# ✅ Recommended for Claude
"Post tweet with image at /Users/me/photos/sunset.png"

# ❌ Not currently supported in Claude
"Post this image: [pasting an image directly]"

# ✅ Works programmatically
// In code, you can still use base64
{
  "text": "Hello world!",
  "media": [{
    "data": "iVBORw0KGgoAAAANS...",
    "media_type": "image/png"
  }]
}

🧪 测试

该项目包括综合测试：

# Run all tests
npm test

# Run specific test suites
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    # Build TypeScript
npm run dev      # Run in development mode
npm test         # Run tests
npm run lint     # Lint code
npm run format   # Format code

环境变量

创建一个 .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 (if using)
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

# Optional
DEBUG=true  # Enable debug logging

✅ 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删除。

🐛 故障排除

常见问题

“无法验证您的身份”

• 验证所有凭据是否正确
• 检查您的应用程序是否具有“读取和写入”权限
• 对于OAuth 1.0a，重新生成您的访问令牌
• 对于OAuth 2.0，确保令牌具有所需的作用域

“超出费率限制”

• 推特有严格的费率限制（尤其是免费版）
• 请等待15分钟，然后重试
• 考虑升级您的Twitter API访问级别

“媒体上传失败”

• 检查文件大小（图像最大5MB）
• 验证文件格式（仅限JPEG、PNG、GIF）
• 对于OAuth 2.0，请确保 media.write 范围包括在内

“403禁止”

• 您的应用程序可能缺少所需的权限
• 检查您的Twitter开发者门户设置
• 确保您的访问级别支持该操作

调试模式

通过设置启用详细日志记录 DEBUG 环境变量：

{
  "env": {
    "DEBUG": "true",
    // ... other credentials
  }
}

日志位置

• 窗户： %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
• 问题:
• 文档:

对于安全漏洞，请直接发送电子邮件，而不是创建公开问题。

📄 许可证

麻省理工学院

🙏 致谢

这是一个增强的fork @埃内斯纳/推特mcp 它补充道：

• OAuth 2.0身份验证支持
• 用于OAuth 2.0的Twitter/X API v2媒体上传
• OAuth 1.0a的自动v1.1回退
• 免费套餐的全面费率限制
• 增强的错误处理和调试
• 程序化OAuth 2.0令牌生成脚本

最初实施者 @enescinar