X Mcp Server

交流 TypeScript

🚀 X MCP Server - 增强版

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

🚀 快速开始

在开始之前，你需要完成以下准备工作：

一个X开发者账户（可在 developer.x.com 注册）
在开发者门户中创建一个X应用
API凭证（详细设置步骤如下）
安装Node.js 18+

本服务器支持两种认证方法，你可以根据需求进行选择：

OAuth 1.0a：设置更简单，适用于所有功能，包括v1.1回退机制
OAuth 2.0：现代认证方式，部分新功能需要使用该方式

安装步骤

对于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代码版（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设置

获取凭证：在应用的“Keys and tokens”标签中，复制API Key和API Key Secret，生成Access Token和Secret（点击“Generate”），确保访问令牌具有“Read and Write”权限。

所需凭证：

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

获取客户端凭证：在应用的“Keys and tokens”标签中，找到OAuth 2.0 Client ID和Client Secret，并保存用于下一步。
生成用户令牌：选项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，用授权码交换访问令牌。

所需凭证：

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

📚 资源

🤝 贡献

欢迎贡献代码！请按照以下步骤进行：

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

🔒 隐私政策

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

0 条评论
分类：交流