MCP Twitter Server

X（推特）MCP服务器

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

🚀 特性

• 53总工具 -33 Twitter API+20增强的SocialData.tools研究功能
• 高级分析 -线索分析、网络映射、情绪分析、病毒追踪
• 绕过API限制 -增强的研究工具无需Pro tier要求即可工作
• 专业错误处理 -清晰的升级指南和优雅的API密钥处理
• 5工作流程提示 -预构建的自动化模板
• 6动态资源 -实时API文档和状态
• 完全符合MCP -工具、提示和资源支持

📋 快速开始

先决条件

• Node.js 18+
• npm或纱线
• X（Twitter）API证书（基本层最低-200美元/月）

本地安装

1. 克隆并安装

   git clone 
   cd twitter-server
   npm install

1. 环境设置

   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

1. 构建并运行

   npm run build
   npm start

1. 测试服务器

   # 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访问级别

🛠️ 可用工具（共53个）

🐦 Twitter API工具（33个工具）

✅ 推特操作（全部正常）

• postTweet -发布新推文
• getTweetById -检索特定推文
• replyToTweet -回复推文
• deleteTweet -删除您的推文

✅ 敬业度（全部工作）

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

✅ 用户管理（最有效）

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

✅ 列表管理（全部工作）

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

⚠️ 搜索和分析（有限）

• searchTweets -搜索推文（需要专业级别-每月5000美元）
• getHashtagAnalytics -标签分析（需要Pro层）
• getLikedTweets -获取点赞推文（API访问问题）

🔍 SocialData.tools增强研究（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密钥设置

Twitter API（必需）

从以下地址获取这些 Twitter开发者门户:

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

启用20种增强的研究工具，以绕过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比较

推荐工作流程

1. 从Twitter API工具开始 用于发布、参与和基本操作
2. 使用SocialData.tools 用于研究、分析和高级见解
3. 两者结合 用于全面的Twitter自动化和分析

🎯 MCP工作流提示

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

1.推文组成(compose-tweet)

创建带有标签、提及和媒体的引人入胜的推文的互动指南。

2.分析报告(analytics-report)

全面的X（推特）分析工作流程，用于业务洞察。

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工具工作 在基础层
• 4工具有限公司 按API层/权限
• 专业错误消息 有升级指导
• 所有核心功能 运营的

🔧 集成示例

MCP客户端（光标/克劳德）

{
  "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文档

推特操作

发布推文

{
  "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"
}

用户操作

get用户信息

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

follow用户

{
  "username": "target_username"
}

参与

可能，

{
  "tweetId": "1234567890123456789"
}

转发

{
  "tweetId": "1234567890123456789"
}

🚨 错误处理

专业错误消息

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

• 明确的API层说明 对于有限的工具
• 升级定价信息 （专业级每月5000美元）
• 直接升级链接 Twitter开发者门户
• 替代解决方案建议

错误响应示例：

{
  "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层限制

• 搜索推文：需要专业级别（每月5000美元）
• getHashtagAnalytics：需要专业版
• getFollowers/getFollower：需要特殊权限（403错误）
• 获得点赞推特：参数验证问题

建议

• 当前设置：非常适合基本的X（推特）自动化
• 用于高级分析：考虑专业级升级
• 关注者/追随者：请求提升权限

🆘 故障排除

常见问题

错误：“未定义fetch”

# Ensure Node.js 18+ 
node --version

403权限错误

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

400错误请求

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

获取帮助

1. 检查错误消息 -我们增强的错误处理提供了明确的指导
2. 审查API文件 -X（推特）开发者门户
3. 先用工作工具测试 -验证基本设置
4. 检查环境变量 -确保设置了所有凭据

______________________________________________________________________

📊 当前状态

• 53总工具：33 Twitter API+20 SocialData.tools增强研究
• 高级分析：线索分析、网络映射、情绪分析、病毒追踪
• 优雅的API密钥处理：当API密钥丢失时，增强的工具会显示有用的设置说明
• 绕过API限制：研究工具无需Twitter Pro级别要求即可工作
• 专业错误处理：明确的升级指导和用户友好的信息
• 完全符合MCP：工具、提示、资源
• 生产就绪：增强的可靠性、全面的分析和出色的用户体验

内置于❤️ 使用模型上下文协议和SocialData.tools集成