MCP服务器

Name: MCP服务器
Author: mbelinky

作者：mbelinky12 星标更新：2025-06-28

安装使用来源：spider==github.com

项目介绍

X MCP Server - 增强版

这是一个增强型的模型上下文协议（MCP）服务器，为X平台增加了OAuth 2.0支持、v2 API媒体上传以及全面的速率限制功能。

✨ 功能

发布推文：创建带有可选媒体附件（图片、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作为回退方案。

📋 先决条件

开始之前，请确保你已经具备以下条件：

一个X开发者账户（在developer.x.com注册）。
在开发者门户中创建的X应用。
API凭证（详见下文设置）。
安装了Node.js 18+。

🔐 认证设置

此服务器支持两种认证方法。根据需要选择：

OAuth 1.0a：设置简单，适用于所有功能，包括v1.1回退。
OAuth 2.0：现代认证方式，某些新功能所需。

设置您的X应用

创建开发者账户：
- 访问developer.x.com。
- 使用Twitter账户登录。
- 如果尚未申请，申请开发者权限。
创建新应用：
- 导航至Twitter开发者门户。
- 点击“项目与应用”→“新建项目”。
- 给项目命名。
- 选择您的使用案例。
- 在项目内创建新应用。
配置应用权限：
- 在应用设置中，进入“用户认证设置”。
- 点击“设置”。
- 启用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 设置

获取您的凭证：
- 在应用的“密钥和令牌”标签页中。
- 复制您的API密钥和API密钥秘密。
- 生成访问令牌和秘密（点击“生成”）。
- 确保访问令牌具有“读写”权限。

所需凭证：

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 设置

获取客户端凭证：
- 在应用的“密钥和令牌”标签页中。
- 查找OAuth 2.0客户端ID和客户端秘密。
- 保存这些信息用于下一步。
生成用户令牌：

选项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 - 手动设置：
- 使用OAuth 2.0流程和PKCE。
- 必要范围：tweet.read，tweet.write，users.read，media.write，offline.access。
- 使用授权码交换访问令牌。

所需凭证：

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桌面

通过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"
      }
    }
  }
}

从源代码安装：

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": {
        // ... 您的凭证
      }
    }
  }
}

重启Claude桌面

对于Claude Code（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"

🛠️ 可用工具

安装完成后，Claude可以使用以下工具：

`post_tweet`

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

示例提示：

"发布一条推文说'来自Claude的问候！'"
"发布这张图片，附上说明'看看这景色！'"（附加图片）
"回复推文ID 123456789，内容为'很好的观点！'"

`search_tweets`

搜索推文，自定义结果数量（10-100）。

示例提示：

"搜索关于#MachineLearning的推文"
"查找最近提到@ClaudeAI的50条推文"
"搜索关于TypeScript教程的推文"

`delete_tweet`

通过其ID删除推文。

示例提示：

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

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

📸 媒体上传注意事项

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

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

示例用法：

# ✅ 推荐用于Claude
"发布带有图片的推文，图片位于/Users/me/photos/sunset.png"

# ❌ 当前不支持在Claude中使用
"发布这张图片：[直接粘贴图片]"

# ✅ 可以在代码中使用
// 在代码中，您仍然可以使用base64
{
  "text": "你好世界！",
  "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删除。

🐛 故障排除

常见问题

“无法验证您”

验证所有凭证是否正确。
检查您的应用是否有“读写”权限。
对于OAuth 1.0a，重新生成访问令牌。
对于OAuth 2.0，确保令牌具有所需的范围。

“超出速率限制”

Twitter有严格的速率限制（尤其是免费层级）。
等待15分钟后再试。
考虑升级您的Twitter API访问级别。

“媒体上传失败”

检查文件大小（最大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

📚 资源

🤝 贡献

欢迎贡献！请：

分叉仓库。
创建功能分支。
为新功能添加测试。
确保所有测试通过。
提交拉取请求。

🔒 隐私政策

此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认证支持
Twitter/X API v2媒体上传支持OAuth 2.0
自动v1.1回退支持OAuth 1.0a
全面的免费层级速率限制
增强的错误处理和调试
程序化OAuth 2.0令牌生成脚本

原始实现由@enescinar提供。