使用说明

A Model Context Protocol server that lets AI assistants interact with Twitter/X.
Built in Go, designed to be simple and useful.

Getting Started • Tools • Scheduling • Security • Docker • Contributing

🎯 它能做什么？

此MCP使您的AI助手能够：

阅读您的时间线、提及、搜索推文和浏览用户资料
写帖子、帖子、回复、点赞和转发
分析热门评分系统的热门话题（过去24小时）
探索按地点分类的热门话题
管理书签和关注/取消关注用户
日程推特和帖子供以后发布

🚀 入门

1.获取您的Twitter API证书

前往 Twitter开发者门户并创建一个应用程序。您需要：

API密钥和秘密 （用于发布、点赞、转发）
访问令牌和密码 （代表您的帐户行事）--确保权限设置为 读取和写入
持有者令牌 （用于读取公共数据）

⚠️ 注意：推特的免费版非常有限。为了获得完整的功能（趋势、搜索、时间线），您至少需要基本级别（每月100美元）。

2.选择您的运输方式

Twitter MCP支持两种传输模式：

STDIO（简单，供本地使用）

server:
  name: "twitter-mcp"
  version: "0.1.0"
  transport:
    type: "stdio"

twitter:
  api_key: "$TWITTER_API_KEY"
  api_key_secret: "$TWITTER_API_KEY_SECRET"
  access_token: "$TWITTER_ACCESS_TOKEN"
  access_token_secret: "$TWITTER_ACCESS_TOKEN_SECRET"
  bearer_token: "$TWITTER_BEARER_TOKEN"

# Optional: path to the scheduling queue file (default: schedule.yaml)
schedule_file: "schedule.yaml"

HTTP（生产，支持身份验证）

server:
  name: "twitter-mcp"
  version: "0.1.0"
  transport:
    type: "http"
    http:
      host: ":8080"

middleware:
  jwt:
    enabled: true
    jwks_uri: "https://your-idp.com/.well-known/jwks.json"
    cache_interval: 5m

twitter:
  api_key: "$TWITTER_API_KEY"
  # ... rest of credentials

schedule_file: "schedule.yaml"

看 docs/config-stdio.yaml 和 docs/config-http.yaml 如需查看完整示例。

3.构建和运行

go mod tidy
make build
./bin/twitter-mcp -config config.yaml

🛠️ 可用工具

阅读

工具	它做什么
`get_me`	获取您的帐户信息
`get_timeline`	获取您的家庭时间表
`get_mentions`	看看是谁在提到你
`search_tweets`	搜索推文（最近24小时，按最近时间排序）
`get_trends`	获取某个地点的热门话题
`get_user_profile`	按用户名获取用户的个人资料
`get_user_tweets`	获取用户最近的推文
`get_bookmarks`	获取您的书签推文

写作

工具	它做什么
`post_tweet`	发布新推文（支持回复）
`post_thread`	发布一个帖子（多条连接的推文）
`delete_tweet`	删除您的一条推文
`like_tweet`	像推特一样
`unlike_tweet`	删除赞
`retweet`	转发某事
`undo_retweet`	撤销转发
`bookmark_tweet`	为推文添加书签
`remove_bookmark`	删除书签
`follow_user`	关注用户
`unfollow_user`	关注用户

分析

工具	它做什么
`search_topics`	一次搜索多个主题（最近24小时）
`get_topics_heat`	将话题受欢迎程度与热度评分（过去24小时）进行比较

调度

工具	它做什么
`schedule_tweet`	将推文或线程添加到日程安排队列
`schedule_update`	修改预定推文（内容、日期、审核状态）
`schedule_delete`	从队列中删除已安排的推文
`schedule_list`	列出所有已安排的推文，可选择按状态筛选
`schedule_get_publishable`	准备好发布推文
`schedule_publish`	按ID发布特定的预定推文

🔥 热分数解释

当你打电话的时候 get_topics_heat 对于一个主题列表，它返回类似以下内容：

[
  {
    "topic": "kubernetes",
    "tweet_count": 20,
    "total_likes": 1250,
    "total_retweets": 340,
    "total_replies": 89,
    "avg_engagement": 86.2,
    "heat_score": 78.5
  },
  {
    "topic": "podman",
    "tweet_count": 15,
    "total_likes": 120,
    "total_retweets": 25,
    "avg_engagement": 10.7,
    "heat_score": 51.2
  }
]

分数（0-100）结合了推特数量和参与度。结果从最热到最冷进行排序。只有推特来自 过去24小时 按新旧程度排序。

📅 安排推文

调度系统允许您将推文和线程排队，以便以后发布。所有内容都存储在本地YAML文件中，因此可以在重启后继续使用。

运作原理

添加推特或帖子 schedule_tweet --设置内容、日期和类型
审查它与 schedule_update （套 reviewed: true)当你对此感到满意时
时机成熟时，AI会呼叫 schedule_get_publishable 检查准备好了什么
AI呼叫 schedule_publish 使用ID进行发布

人工智能始终处于循环中——没有任何东西会自动发布。

状态

状态	含义
`pending`	已添加但尚未审核
`reviewed`	已批准，准备在时间到来时发布
`published`	已成功发布
`failed`	出了点问题（检查 `fail_reason`)

示例

AI: schedule_tweet
  type: "tweet"
  content: ["Just shipped a new feature 🚀"]
  scheduled_at: "2026-02-25T10:00:00Z"

AI: schedule_update
  id: "abc-123"
  reviewed: true

# Later...
AI: schedule_get_publishable
  min_hours_since_last: 2

AI: schedule_publish
  id: "abc-123"

🔐 身份验证和安全

在HTTP模式下运行时，Twitter MCP使用JWKS端点在本地验证JWT：

JWT验证 针对远程JWKS端点（具有本地缓存）
CEL 表达式 用于JWT有效载荷上的细粒度允许条件
工具政策 基于JWT声明（组、范围等）
OAuth 2.0元数据端点 （符合RFC 9728）
访问日志记录 带有标题编辑功能

JWT有效负载被解码并通过请求上下文传递，使其可用于工具策略中间件，而无需任何额外的解码。

工具政策

根据JWT声明限制工具访问：

policies:
  tools:
    # Admins can do everything
    - expression: 'payload.groups.exists(g, g == "admins")'
      allowed_tools: ["*"]
    
    # Writers can post and read
    - expression: 'payload.groups.exists(g, g == "writers")'
      allowed_tools: ["post_*", "get_*", "like_*", "retweet", "schedule_*"]
    
    # Readers can only read
    - expression: 'payload.scope.contains("twitter:read")'
      allowed_tools: ["get_*", "search_*"]

支持的模式：

精确匹配： "post_tweet"
通配符： "*" （所有工具）
前缀： "get_*" （所有工具以 get_)

🐳 码头工人

构建并运行

docker build -t twitter-mcp .
docker run -v $(pwd)/config.yaml:/config/config.yaml twitter-mcp

Docker Compose

# Set environment variables
export TWITTER_API_KEY=your_key
export TWITTER_API_KEY_SECRET=your_secret
# ... etc

# Run
docker-compose up -d

🌍 趋势的位置代码

这 get_trends 该工具使用WOEID（Where On Earth ID）：

位置	WOEID
🌍 全球	1
🇪🇸 西班牙	23424950
🇺🇸 美国	23424977
🇬🇧 英国	23424975
马德里	766273
巴塞罗那	753692
纽约	2459115

🔧 故障排除

请求频率超限

Twitter API有严格的费率限制。请等待几分钟，然后重试，或降低请求频率。

无法验证您的身份

检查您的OAuth凭据。对于发布，您需要OAuth 1.0a令牌 读取和写入 权限。如果在生成令牌后更改了权限，请从开发人员门户重新生成它们。

已部署信用额度

API信用额度已用完。检查您的Twitter开发者门户以充值或等待每月重置。

工具访问被拒绝

如果配置了策略，但您得到“拒绝访问”，请确保您的JWT包含与策略匹配的所需声明（组、范围）。

计划推文未出现在get_publishable中

检查：（1）推特有 reviewed: true, (2) scheduled_at （3）自上次发布推文以来，已经过去了足够的时间(min_hours_since_last).

🤝 贡献

欢迎投稿！看贡献.md 作为指导方针。

有关处理此代码库的AI代理，请参阅代理商.md.

📄 许可证

Apache 2.0