技术文档摘要

X（推特）MCP服务器

一个全面的模型上下文协议服务器实现，用于与X（推特）API集成的专业工作流程自动化、增强的错误处理和实时文档。

🚀 特性

• 总计53个工具 - 33个推特API + 20个增强的社会数据研究能力
• 高级分析 - 线程分析、网络映射、情感分析、病毒传播追踪
• 绕过API限制 - 增强的研究工具无需专业层级要求
• 专业错误处理 - 清晰的升级指导和优雅的API密钥处理
• 5个工作流提示 - 预构建的自动化模板
• 6个动态资源 - 实时API文档和状态
• 完全符合MCP规范 - 工具、提示和资源支持

📋 快速开始

先决条件

• Node.js 18+
• npm 或 yarn
• X（推特）API凭证（最低基础层 - 每月$200）

本地安装

1. 克隆并安装

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

2. 环境设置

   cp .env.example .env
   # 使用你的凭证编辑 .env
   

   必需的环境变量：

   # 推特API凭证（必需）
   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密钥（可选 - 启用增强的研究工具）
   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   SOCIALDATA_BASE_URL=https://api.socialdata.tools  # 可选，默认使用此URL
   

3. 构建并运行

   npm run build
   npm start
   

4. 测试服务器

   # 使用JSON-RPC调用测试
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js
   
   # 测试特定工具
   source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js
   

🔑 X（推特）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访问级别

层级	成本	正常工作的工具	有限的工具
基础	$200/月	18/22个工具	searchTweets, getHashtagAnalytics
专业	$5,000/月	所有22个工具	无

🛠️ 可用工具（总计53个）

🐦 推特API工具（33个工具）

✅ 发帖操作（全部正常工作）

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

✅ 互动（全部正常工作）

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

✅ 用户管理（大部分正常工作）

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

✅ 列表管理（全部正常工作）

• createList - 创建X（推特）列表
• getUserLists - 获取用户的列表
• addUserToList / removeUserFromList - 管理列表成员
• getListMembers - 获取列表成员

⚠️ 搜索与分析（有限）

• searchTweets - 搜索推文（需要专业层级 - 每月$5,000）
• getHashtagAnalytics - 带标签分析（需要专业层级）
• getLikedTweets - 获取点赞的推文（API访问问题）

🔍 社交数据工具增强研究（20个工具）

注意：这些工具在缺少API密钥时会显示有用的设置说明

🔎 高级搜索（6个工具）

• advancedTweetSearch - 复杂查询，绕过API层级限制
• historicalTweetSearch - 访问超出标准API限制的历史推文
• trendingTopicsSearch - 实时趋势分析和热门内容发现
• bulkUserProfiles - 单次请求多用户资料分析
• userGrowthAnalytics - 时间跨度上的用户增长模式分析
• userInfluenceMetrics - 互动评分和影响力计算

🧵 线程及对话分析（3个工具）

• getFullThread - 重建完整的推特线程及其互动指标
• getConversationTree - 映射对话结构，包括回复和引用
• getThreadMetrics - 线程性能分析和互动分布

🌐 网络分析（3个工具）

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

📈 高级分析（3个工具）

• getHashtagTrends - 带标签表现跟踪及趋势分析
• analyzeSentiment - 情感分析及关键词频率跟踪
• trackVirality - 病毒传播模式及互动速度分析

📱 直接消息及管理（5个工具）

• 各种DM和用户管理工具

🔑 API密钥设置

推特API（必需）

从推特开发者门户获取：

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（可选）

启用20个增强的研究工具，绕过推特API限制：

1. 注册于社交数据工具
2. 获取你的API密钥从仪表盘
3. 添加到.env文件：

   SOCIALDATA_API_KEY=your_socialdata_api_key_here
   

没有社交数据API密钥： 增强的研究工具将显示有用的设置说明而不是错误。

🧪 测试社交数据工具集成

测试增强研究工具

# 测试高级推文搜索（绕过推特API专业层级要求）
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

# 测试情感分析
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "analyzeSentiment", "arguments": {"query": "ChatGPT", "sampleSize": 20}}}' | node dist/index.js

# 测试用户影响力指标
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "userInfluenceMetrics", "arguments": {"username": "openai"}}}' | node dist/index.js

# 测试线程分析
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getFullThread", "arguments": {"tweetId": "1234567890123456789"}}}' | node dist/index.js

在没有API密钥的情况下测试

# 这些将显示有用的设置说明而不是错误
SOCIALDATA_API_KEY="" echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "advancedTweetSearch", "arguments": {"query": "test"}}}' | node dist/index.js

🆚 何时使用哪种工具

推特API vs 社交数据工具比较

使用场景	推特API工具	社交数据工具替代方案	优势
基本搜索	searchTweets ⚠️（专业层级$5k/月）	advancedTweetSearch ✅	绕过API限制
用户分析	getUserInfo ✅	userInfluenceMetrics ✅	增强分析
历史数据	受API层级限制	historicalTweetSearch ✅	访问旧推文
情感分析	不可用	analyzeSentiment ✅	内置情感评分
线程分析	手动重建	getFullThread ✅	自动化线程映射
网络映射	不可用	mapInfluenceNetwork ✅	连接分析
带标签趋势	getHashtagAnalytics ⚠️（专业层级）	getHashtagTrends ✅	无层级限制

推荐工作流程

1. 首先使用推特API工具进行发布、互动和基本操作
2. 使用社交数据工具进行研究、分析和高级洞察
3. 结合两者进行全面的推特自动化和分析

🎯 MCP工作流提示

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

1. 发帖创作（compose-tweet）

交互式指导创建带有标签、提及和媒体的吸引人的推文。

2. 分析报告（analytics-report）

全面的X（推特）分析工作流，提供商业洞察。

3. 内容策略（content-strategy）

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

4. 社区管理（community-management）

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

5. 带标签研究（hashtag-research）

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

📊 动态资源

实时信息可通过MCP访问：

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

🧪 测试

手动测试

# 测试正常工作的工具
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "postTweet", "arguments": {"text": "来自MCP的问候！"}}}' | node dist/index.js

# 测试用户信息
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "getUserInfo", "arguments": {"username": "elonmusk"}}}' | node dist/index.js

# 测试受限工具（将显示升级指导）
source .env && echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "searchTweets", "arguments": {"query": "MCP"}}}' | node dist/index.js

测试结果总结

• 基础层级上18个工具正常工作
• 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

# 总是先源环境
source .env

# 列出所有工具
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

# 调用特定工具
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "toolName", "arguments": {"param": "value"}}}' | node dist/index.js

📝 API文档

发帖操作

postTweet

{
  "text": "您的推文内容（最多280个字符）"
}

getTweetById

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

replyToTweet

{
  "tweetId": "1234567890123456789", 
  "text": "您的回复内容"
}

用户操作

getUserInfo

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

followUser

{
  "username": "目标用户名"
}

互动

likeTweet

{
  "tweetId": "1234567890123456789"
}

retweet

{
  "tweetId": "1234567890123456789"
}

🚨 错误处理

专业错误消息

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

• 清晰的API层级解释对于受限工具
• 升级定价信息（每月$5,000专业层级）
• 直接升级链接至推特开发者门户
• 替代解决方案建议

示例错误响应：

{
  "error": "此端点需要X（推特）API专业层级访问（每月$5,000）。访问 https://developer.twitter.com/en/docs/twitter-api/getting-started/about-twitter-api#v2-access-level 升级您的访问级别。"
}

📁 项目结构

twitter-server/
├── src/
│   ├── handlers/          # API端点处理器
│   ├── prompts.ts        # MCP工作流提示  
│   ├── resources.ts      # 动态MCP资源
│   └── index.ts          # 主MCP服务器
├── dist/                 # 编译JavaScript
├── scripts/              # 文档及PRD
└── package.json

🔄 开发

构建 & 运行

npm run build    # 编译TypeScript
npm start        # 启动生产服务器
npm run dev      # 开发模式，监视更改

添加新工具

1. 在适当的src/handlers/文件中添加处理函数
2. 在src/index.ts中注册工具
3. 在此README中添加文档
4. 使用JSON-RPC调用测试

贡献

1. 遵循现有的代码模式
2. 添加适当的专业错误处理
3. 测试成功和失败的情况
4. 更新文档

📋 已知限制

API层级限制

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

建议

• 当前设置：适用于基本X（推特）自动化
• 对于高级分析：考虑升级到专业层级
• 对于粉丝/关注者：请求提升权限

🆘 故障排除

常见问题

错误：“fetch未定义”

# 确保Node.js版本为18+
node --version

403权限错误

• 检查API凭证是否正确
• 验证账户是否有必要的权限