X (Twitter) MCP Server

X (Twitter) MCP 服务

一个全面的 Model Context Protocol 服务实现，用于 X (Twitter) API 集成，具备专业的工作流自动化、增强的错误处理以及实时文档。

🚀 功能

• 共 53 个工具 - 33 个 Twitter API + 20 个增强的 SocialData.tools 研究能力
• 高级分析 - 推文串分析、网络映射、情感分析、病毒式传播追踪
• 绕过 API 限制 - 增强的研究工具无需 Pro 套餐即可使用
• 专业的错误处理 - 清晰的升级指引和优雅的 API 密钥处理
• 5 个工作流提示词 - 预构建的自动化模板
• 6 个动态资源 - 实时 API 文档和状态
• 完全符合 MCP 规范 - 支持工具、提示词和资源

📋 快速开始

前置条件

• Node.js 18+
• npm 或 yarn
• X (Twitter) API 凭据（最低 Basic 套餐 - $200/月）

本地安装

1. 克隆并安装

   git clone <repository-url>
   cd twitter-server
   npm install
   

2. 环境配置

   cp .env.example .env
   # Edit .env with your credentials
   

   必需的环境变量：

   # Twitter API credentials (Required)
   X_API_KEY=your_api_key_here
   X_API_SECRET=your_api_secret_here  
   X_ACCESS_TOKEN=your_access_token_here
   X_ACCESS_TOKEN_SECRET=your_access_token_secret_here
   
   # SocialData.tools API key (Optional - enables enhanced research tools)
   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   SOCIALDATA_BASE_URL=https://api.socialdata.tools  # Optional, uses default if not set
   

3. 构建并运行

   npm run build
   npm start
   

4. 测试服务

   # Test with JSON-RPC calls
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js
   
   # Test specific tool
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js
   

🔑 X (Twitter) API 设置

必需的凭据

将以下内容添加到你的 .env 文件中：

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

API 访问级别

套餐	费用	可用工具	受限工具
Basic	$200/月	18/22 个工具	searchTweets、getHashtagAnalytics
Pro	$5,000/月	全部 22 个工具	无

🛠️ 可用工具（共 53 个）

🐦 Twitter API 工具（33 个工具）

✅ 推文操作（全部可用）

• postTweet - 发布新推文
• getTweetById - 获取特定推文
• replyToTweet - 回复推文
• deleteTweet - 删除你的推文

✅ 互动（全部可用）

• likeTweet / unlikeTweet - 点赞/取消点赞推文
• retweet / undoRetweet - 转发/取消转发推文
• getRetweets - 获取转发用户

✅ 用户管理（大部分可用）

• getUserInfo - 获取用户资料 ✅
• getUserTimeline - 获取用户推文 ✅
• followUser / unfollowUser - 关注/取消关注用户 ✅
• getFollowers - 获取关注者 ⚠️（403 - 需要特殊权限）
• getFollowing - 获取正在关注 ⚠️（403 - 需要特殊权限）

✅ 列表管理（全部可用）

• createList - 创建 X (Twitter) 列表
• getUserLists - 获取用户的列表
• addUserToList / removeUserFromList - 管理列表成员
• getListMembers - 获取列表成员

⚠️ 搜索与分析（受限）

• searchTweets - 搜索推文（需要 Pro 套餐 - $5,000/月）
• getHashtagAnalytics - 话题标签分析（需要 Pro 套餐）
• getLikedTweets - 获取点赞的推文（API 访问问题）

🔍 SocialData.tools 增强研究（20 个工具）

注意：这些工具在缺少 API 密钥时会优雅处理，并提供有用的设置说明

🔎 高级搜索（6 个工具）

• advancedTweetSearch - 使用运算符的复杂查询，绕过 API 套餐限制
• historicalTweetSearch - 访问超出标准 API 限制的历史推文
• trendingTopicsSearch - 实时趋势分析和热门内容发现
• bulkUserProfiles - 在单次请求中进行多用户资料分析
• userGrowthAnalytics - 随时间变化的用户增长模式分析
• userInfluenceMetrics - 互动评分和影响力计算

🧵 推文串与对话分析（3 个工具）

• getFullThread - 重建完整的 Twitter 推文串并附带互动指标
• getConversationTree - 映射对话结构，包括回复和引用
• getThreadMetrics - 推文串性能分析和互动分布

🌐 网络分析（3 个工具）

• findMutualConnections - 通过互动发现共同联系
• analyzeFollowerDemographics - 关注者模式和人口统计分析
• mapInfluenceNetwork - 影响力映射和连接强度分析

📈 高级分析（3 个工具）

• getHashtagTrends - 随时间追踪话题标签表现并进行趋势分析
• analyzeSentiment - 情感分析并追踪关键词频率
• trackVirality - 病毒式传播模式与互动速度分析

📱 私信与内容管理（5 个工具）

• 各种私信和用户管理工具

🔑 API 密钥设置

Twitter（必需）

从 Twitter Developer Portal 获取这些密钥：

X_API_KEY=your_api_key_here
X_API_SECRET=your_api_secret_here  
X_ACCESS_TOKEN=your_access_token_here
X_ACCESS_TOKEN_SECRET=your_access_token_secret_here

SocialData.tools API（可选）

启用 13 个增强研究工具，绕过 Twitter API 的限制：

1. 注册 SocialData.tools
2. 从仪表板获取你的 API 密钥
3. 添加到 .env 文件：

   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   

没有 SocialData API 密钥时： 增强研究工具将显示有用的设置说明，而不是错误。

🧪 测试 SocialData.tools 集成

测试增强研究工具

# Test advanced tweet search (bypasses Twitter API Pro tier requirement)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "AI OR machine learning", "maxResults": 5}}}' | node dist/index.js

# Test sentiment analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "analyzeSentiment", "arguments": {"query": "ChatGPT", "sampleSize": 20}}}' | node dist/index.js

# Test user influence metrics
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "userInfluenceMetrics", "arguments": {"username": "openai"}}}' | node dist/index.js

# Test thread analysis
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getFullThread", "arguments": {"tweetId": "1234567890123456789"}}}' | node dist/index.js

无 API 密钥测试

# These will show helpful setup instructions instead of errors
SOCIALDATA_API_KEY="" echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "test"}}}' | node dist/index.js

🆚 何时使用哪些工具

Twitter API 与 SocialData.tools 对比

使用场景	Twitter API 工具	SocialData.tools 替代方案	优势
基本搜索	searchTweets ⚠️（Pro 套餐 $5k/月）	advancedTweetSearch ✅	绕过 API 限制
用户分析	getUserInfo ✅	userInfluenceMetrics ✅	增强分析
历史数据	受 API 套餐限制	historicalTweetSearch ✅	访问更早的推文
情感分析	不可用	analyzeSentiment ✅	内置情感分析
线程分析	手动重建	getFullThread ✅	自动线程映射
网络映射	不可用	mapInfluenceNetwork ✅	连接分析
话题标签趋势	getHashtagAnalytics ⚠️（Pro 套餐）	getHashtagTrends ✅	无套餐限制

推荐工作流

1. 从 Twitter API 工具开始，用于发布、互动和基本操作
2. 使用 SocialData.tools 进行研究、分析和高级洞察
3. 结合两者，实现全面的 Twitter 自动化和分析

🎯 MCP 工作流提示词

我们的服务包含 7 个专业工作流模板：

1. 推文撰写（compose-tweet）

创建包含话题标签、提及和媒体的吸引力推文的交互式指导。

2. 分析报告（analytics-report）

面向业务洞察的全面 X（Twitter）分析工作流。

3. 内容策略（content-strategy）

战略内容规划和受众互动工作流。

4. 社区管理（community-management）

客户服务和社区互动最佳实践。

5. 话题标签研究（hashtag-research）

特定行业的话题标签研究和趋势分析。

📊 动态资源

可通过 MCP 访问的实时信息：

• API 速率限制 - 实时使用监控
• 访问级别状态 - 当前套餐能力
• 工具状态报告 - 可用与受限工具
• 快速入门指南 - 入门文档
• 工作流模板 - 预构建的自动化示例
• 用户资料数据 - 动态用户信息（实时 API 调用）

🧪 测试

手动测试

# Test working tools
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "postTweet", "arguments": {"text": "Hello from MCP!"}}}' | node dist/index.js

# Test user info
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

# Test limited tools (will show upgrade guidance)
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "searchTweets", "arguments": {"query": "MCP"}}}' | node dist/index.js

测试结果摘要

• 18 个工具可用（Basic 套餐）
• 4 个工具受限（受 API 套餐/权限限制）
• 专业错误消息，附带升级指导
• 所有核心功能正常运行

🔧 集成示例

MCP 客户端（Cursor/Claude）

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/path/to/twitter-server/dist/index.js"],
      "env": {
        "X_API_KEY": "your_api_key",
        "X_API_SECRET": "your_api_secret", 
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret"
      }
    }
  }
}

直接 JSON-RPC

# Always source environment first
source .env

# List all tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# Call specific tool
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "toolName", "arguments": {"param": "value"}}}' | node dist/index.js

📝 API 文档

推文操作

postTweet

{
  "text": "Your tweet content (up to 280 characters)"
}

getTweetById

{
  "tweetId": "1234567890123456789",
  "tweetFields": ["created_at", "public_metrics", "author_id"]
}

replyToTweet

{
  "tweetId": "1234567890123456789", 
  "text": "Your reply content"
}

用户操作

getUserInfo

{
  "username": "elonmusk",
  "fields": ["description", "public_metrics", "profile_image_url"]
}

followUser

{
  "username": "target_username"
}

互动

likeTweet

{
  "tweetId": "1234567890123456789"
}

retweet

{
  "tweetId": "1234567890123456789"
}

🚨 错误处理

专业的错误消息

我们增强的错误处理提供：

• 针对受限工具的清晰 API 层级说明
• 升级价格信息（每月 $5,000 的 Pro 层级）
• 直接升级链接，指向 Twitter Developer Portal
• 替代方案建议

错误响应示例：

{
  "error": "This endpoint requires X (Twitter) API Pro tier access ($5,000/month). Visit https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api#v2-access-leve to upgrade your access level."
}

📁 项目结构

twitter-server/
├── src/
│   ├── handlers/          # API endpoint handlers
│   ├── prompts.ts        # MCP workflow prompts  
│   ├── resources.ts      # Dynamic MCP resources
│   └── index.ts          # Main MCP server
├── dist/                 # Compiled JavaScript
├── scripts/              # Documentation & PRD
└── package.json

🔄 开发

构建与运行

npm run build    # Compile TypeScript
npm start        # Start production server
npm run dev      # Development mode with watch

添加新工具

1. 在相应的 src/handlers/ 文件中添加处理函数
2. 在 src/index.ts 中注册工具
3. 添加文档到本 README
4. 使用 JSON-RPC 调用进行测试

贡献

1. 遵循现有代码模式
2. 添加带有专业消息的适当错误处理
3. 在正常和失败场景下都进行测试
4. 更新文档

📋 已知限制

API 层级限制

• searchTweets：需要 Pro 层级（每月 $5,000）
• getHashtagAnalytics：需要 Pro 层级
• getFollowers/getFollowing：需要特殊权限（403 错误）
• getLikedTweets：参数验证问题

建议

• 当前设置：非常适合基础的 X (Twitter) 自动化
• 对于高级分析：考虑升级到 Pro 层级
• 对于 Followers/Following：申请提升权限

🆘 故障排除

常见问题

错误："fetch is not defined"

# Ensure Node.js 18+ 
node --version

403 权限错误

• 检查 API 凭据是否正确
• 验证账户是否具有所需权限
• 某些端点需要特殊审批

400 Bad Request 错误

• 检查参数格式
• 查看我们增强的错误消息以获取指导
• 验证 API 层级是否支持该端点

获取帮助

1. 查看错误消息 - 我们增强的错误处理提供清晰指导
2. 查阅 API 文档 - X (Twitter) Developer Portal
3. 先用可用的工具测试 - 验证基础设置
4. 检查环境变量 - 确保所有凭据均已设置

---

📊 当前状态

• 53 个工具总计：33 个 Twitter API + 20 个 SocialData.tools 增强研究
• 高级分析：线程分析、网络映射、情感分析、病毒式传播追踪
• 优雅的 API 密钥处理：增强工具在缺少 API 密钥时显示有用的设置说明
• 绕过 API 限制：研究工具无需 Twitter Pro 层级要求即可使用
• 专业的错误处理：清晰的升级指导和对用户友好的消息
• 完全符合 MCP 规范：工具、提示词、资源
• 生产就绪：增强的可靠性、全面的分析和出色的用户体验

使用 Model Context Protocol 和 SocialData.tools 集成，以 ❤️ 构建