TwittrAPI

twittrapi-mcp – 为 Claude、Cursor 和其他 AI Agent 提供的 Twitter/X MCP 服务

这是一个适用于 TwittrAPI 的 MCP 服务。TwittrAPI 是一个面向公开 Twitter/X 数据的 REST API，涵盖推文、个人资料、关注者、搜索、列表和社群。它让 Claude、Cursor 和其他 MCP 客户端能够读取这些数据，每 1,000 次调用低至 $0.065，且无需 X 开发者账号。

获取 API 密钥： twittrapi.com/start · 价格 · 文档 · 状态 · 也可通过 RapidAPI 使用

SDK 和集成： Python · Node.js · Go · n8n · Make · Apify · LangChain · LlamaIndex · Agent 技能 · 示例

与 X Corp. 无关联。

托管服务（无需安装）

支持远程 MCP 服务的应用可以改用 URL 连接（托管版本提供此功能；请参阅 twittrapi.com/docs/hosted-mcp）：

https://mcp.twittrapi.com/mcp

客户端	设置
Claude.ai / Claude Desktop	前往 Settings > Connectors > Add custom connector，粘贴 URL，点击 Connect，登录 TwittrAPI 并授权访问（OAuth）
ChatGPT	前往 Settings > Apps & Connectors > Advanced settings > Developer mode，然后使用 URL 和 OAuth 进行创建
Claude Code	执行 claude mcp add --transport http twittrapi https://mcp.twittrapi.com/mcp（OAuth），或添加 --header "Authorization: Bearer $TWITTRAPI_API_KEY"
Cursor	在 mcp.json 中添加 {"mcpServers": {"twittrapi": {"url": "https://mcp.twittrapi.com/mcp", "headers": {"X-API-KEY": "${env:TWITTRAPI_API_KEY}"}}}}
VS Code	在 .vscode/mcp.json 中添加 {"servers": {"twittrapi": {"type": "http", "url": "https://mcp.twittrapi.com/mcp"}}}（OAuth）

使用 OAuth 时，应用永远不会看到你的 API 密钥；调用费用会从你的余额中扣除，与其他调用相同。已连接的应用会列在控制面板的 Connected apps 下，你也可以在此断开连接。

所需条件

• Node.js 20 或更新版本
• TwittrAPI 密钥，或已订阅 Twitter AIO API 的 RapidAPI 密钥

每次工具调用都会计为你账户中的一次计费 API 调用。

安装

Claude Code

claude mcp add twittrapi --env TWITTRAPI_API_KEY=your-key -- npx -y twittrapi-mcp

Claude Desktop

打开 Settings > Developer > Edit Config，并将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "twittrapi": {
      "command": "npx",
      "args": ["-y", "twittrapi-mcp"],
      "env": {
        "TWITTRAPI_API_KEY": "your-key"
      }
    }
  }
}

之后重启 Claude Desktop。

Cursor

将以下内容添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "twittrapi": {
      "command": "npx",
      "args": ["-y", "twittrapi-mcp"],
      "env": {
        "TWITTRAPI_API_KEY": "your-key"
      }
    }
  }
}

其他客户端

任何能够启动 stdio 服务的客户端都可以使用。命令为 npx -y twittrapi-mcp。

环境变量

变量	必填	描述
TWITTRAPI_API_KEY	两个密钥之一	你的 TwittrAPI 密钥。作为 X-API-KEY 标头发送。
RAPIDAPI_KEY	两个密钥之一	RapidAPI 密钥。仅当未设置 TWITTRAPI_API_KEY 时使用。
RAPIDAPI_HOST	否	你的 RapidAPI 列表的主机。默认值为 twitter-aio.p.rapidapi.com。
TWITTRAPI_BASE_URL	否	直接 API 的基础 URL。默认值为 https://api.twittrapi.com。
TWITTRAPI_RESPONSE_FORMAT	否	simple（默认值）或 raw。请参阅响应格式。
TWITTRAPI_X_COOKIE	否	你自己已登录的 x.com 会话 Cookie。与 TWITTRAPI_X_PROXY 配合使用时启用账户工具。
TWITTRAPI_X_PROXY	否	供账户工具使用的代理，格式为 http://user:pass@host:port。
TWITTRAPI_X_CHAT_PASSCODE	否	你的 X Chat 密码。添加 send_dm 和 list_dm_conversations 中的消息文本。

如果两个密钥都未设置，服务仍会启动并列出其工具，但每次调用都会返回说明如何设置密钥的错误。

改用 RapidAPI

如果你通过 RapidAPI 购买了访问权限，请设置 RAPIDAPI_KEY，而不是 TWITTRAPI_API_KEY：

"env": { "RAPIDAPI_KEY": "your-rapidapi-key" }

请求随后会发送到 https://twitter-aio.p.rapidapi.com，并附带 x-rapidapi-key 和 x-rapidapi-host 标头。工具及其输出保持不变。

如果你订阅了 RapidAPI 上的其他 TwittrAPI 列表，请设置其主机： "RAPIDAPI_HOST": "twttr.p.rapidapi.com"。

工具

这些工具读取公开数据，始终可用。配置 X 会话后，还会添加账户工具。

工具	功能
get_user_by_username	按用户名获取个人资料，包括数字用户 ID
get_user_by_id	按数字用户 ID 获取个人资料
username_to_id	将用户名解析为用户 ID
users_by_ids	一次获取最多 500 个用户 ID 对应的个人资料
get_user_tweets	用户的推文
get_user_tweets_and_replies	用户的推文和回复
get_user_media	用户包含照片或视频的推文
get_followers	用户的关注者
get_following	用户关注的账号
get_verified_followers	用户的认证关注者
get_user_affiliates	与某个组织有关联的账号
get_friendships_batch	查询某个账号是否关注最多 50 个其他账号，以及这些账号是否回关
get_user_about_batch	最多 20 个用户名对应的“关于此账号”信息
search_tweets	使用 X 运算符搜索；可按热门、最新、用户、照片或视频筛选
get_tweet	一条推文及其回复串
tweets_by_ids	一次按 ID 获取最多 100 条推文
get_tweet_retweets	转推某条推文的用户
get_tweet_quotes	引用某条推文的推文
get_tweet_replies	仅获取某条推文的回复
get_tweet_thread	作者围绕某条推文发布的串文
get_list_details	列表名称、所有者和数量
get_list_tweets	列表成员发布的推文
get_list_members	列表成员
get_community	社区详情
get_community_about	社区的“关于”页面：规则、版主、成员
get_community_tweets	社区中的推文
search_communities	按关键词查找社区
get_trends	某个地点（WOEID）的热门话题
get_trend_locations	有热门话题的地点及其 WOEID
get_space	X Space：标题、状态、主持人和参与者

用户时间线工具（get_user_tweets、get_followers 等）接受 userId 或 username。批量工具按每个用户名计费一次；tweets_by_ids 无论 ID 数量多少都只计为一次调用。

账号工具

设置 TWITTRAPI_X_COOKIE 和 TWITTRAPI_X_PROXY 后，服务还会列出可在你自己的 X 账号上执行操作的工具：

工具	功能
create_tweet	发布推文；可选引用推文（quoteUrl）、投票（pollChoices）和回复限制
reply_to_tweet	回复推文
delete_tweet	删除你的一条推文
like_tweet、unlike_tweet	点赞或取消点赞
retweet、unretweet	转发或撤销转发
bookmark_tweet、unbookmark_tweet	添加或移除书签
follow_user、unfollow_user	关注或取消关注（通过 userId 或 username）
list_dm_conversations	查看你的私信收件箱
send_dm	发送私信（需要 TWITTRAPI_X_CHAT_PASSCODE）
create_list	创建列表
add_list_member、remove_list_member	添加或移除列表成员
create_draft、list_drafts	保存草稿、查看你的草稿
list_bookmark_folders、list_bookmark_folder_tweets	查看你的书签文件夹及其中的推文（X Premium）
search_bookmarks	搜索你的书签
list_community_memberships	查看你加入的社群
list_articles、get_article	查看你的 X 文章（草稿或已发布）以及指定文章（X Premium）
create_article、update_article	将新文章保存为草稿、修改文章（X Premium）
publish_article、unpublish_article、delete_article	发布、取消发布或删除文章（X Premium）

如何获取 Cookie 并设置代理：twittrapi.com/docs/x-session。 Cookie 需要包含 auth_token 和 ct0；发送私信还需要 twid。

"env": {
  "TWITTRAPI_API_KEY": "your-key",
  "TWITTRAPI_X_COOKIE": "auth_token=...; ct0=...; twid=u%3D...",
  "TWITTRAPI_X_PROXY": "http://user:pass@host:port"
}

• Cookie 和代理保存在服务的配置中。它们不是工具参数，因此模型不会看到它们，也绝不会被记录或包含在结果中。
• 写入工具标记为 readOnlyHint: false（删除和撤销操作还会标记为 destructiveHint: true），因此客户端会在运行前征求确认。
• 每次调用都会计费，与读取工具一样。
• 账号工具仅在 stdio 模式下可用。HTTP 模式和托管服务不提供这些工具。

响应格式

默认情况下，工具结果使用 API 的简洁格式：扁平的 camelCase JSON，采用固定架构（列表为 {"data": [...], "nextCursor": ..., "hasNextPage": ...}，单个对象为 {"data": {...}}）。推文包含 id、url、text、createdAt、author、counts、media、quoted、retweetOf 等字段；用户包含 username、name、description、counts 等字段。与 X 的原始 GraphQL JSON 相比，这种格式可减少约 60% 的 Token。

若要获取原始 JSON（用于卡片、投票、编辑历史、社群备注和简洁格式未包含的其他字段）：

• 单次调用：工具接受可选的 format 参数，值为 "simple" 或 "raw"；
• 整个服务：设置 TWITTRAPI_RESPONSE_FORMAT=raw（但 format 参数优先级更高）。

部分端点没有简洁格式：get_space、get_community_about、批量工具以及较新的账号工具（书签文件夹和搜索、社群、文章）。这些工具没有 format 参数，始终返回原始 JSON。

输出大小与分页

原始响应可能有数百 KB。每个工具都接受可选的 max_chars 参数（默认值为 50,000，范围为 1,000 至 1,000,000）。超出长度的输出会被截断，并以 [TRUNCATED ...] 标记结尾。

分页工具会在 JSON 上方输出游标，因此截断不会移除游标：

next_cursor: DAABCgABGZ...
Pass next_cursor as `cursor` to get the next page.

{"data":{...}}

在最后一页，标题会显示 next_cursor: none (last page, no more results)。在简洁格式中，此时 hasNextPage 为 false。在原始格式中，以下情况表示没有下一页游标：响应中没有下一页游标（包括点赞时间线为空的情况）、X 返回了你刚发送的游标，或者某页仅包含游标而没有结果。

错误

API 错误会作为工具错误返回，并附带简短说明，例如：

• 402：账户余额不足
• 429：触发速率限制，请稍后重试
• 404：用户或推文不存在、设为私密或已被停用
• 5xx：上游出现暂时性问题

HTTP 模式（远程托管）

npx -y twittrapi-mcp --http --port 3333 --host 0.0.0.0

此模式会在 /mcp 提供无状态的 Streamable HTTP 端点，并在 /health 提供健康检查。默认主机为 127.0.0.1。每个 POST 请求都会创建一个绑定到调用方凭据的独立服务实例，因此可在负载均衡器后运行任意数量的实例，无需粘性会话。GET /mcp 会返回 405（不支持服务端发起的流）；不提供旧版 SSE 传输方式。

在 HTTP 模式下，服务不会使用自身环境中的密钥。每个请求都携带调用方的凭据：

• 对于直接 API，使用 X-API-KEY: <key> 或 Authorization: Bearer <key>
• 对于 RapidAPI，使用 x-rapidapi-key: <key>；如果所用 API 列表不是 twitter-aio.p.rapidapi.com，还需提供 x-rapidapi-host: <host>（必须以 .p.rapidapi.com 结尾）
• Authorization: Bearer twa_at_...：TwittrAPI OAuth 访问令牌（见下文的托管模式）

HTTP 模式不提供账户工具；其中的 TWITTRAPI_X_COOKIE 和 TWITTRAPI_X_PROXY 会被忽略。仍会从环境中读取 TWITTRAPI_BASE_URL 和 TWITTRAPI_RESPONSE_FORMAT；调用方也可以通过 format 参数为每次调用指定格式。如果服务可从互联网访问，请将其置于 HTTPS 后。

使用你自己的实例时的客户端配置示例（Claude Code）：

claude mcp add --transport http twittrapi https://your-host.example.com/mcp --header "X-API-KEY: your-key"

使用 OAuth 的托管模式

对于要求 OAuth 的客户端（Claude.ai 连接器、ChatGPT），服务充当 OAuth 2.1 资源服务器，TwittrAPI 仪表板充当授权服务器（动态客户端注册、PKCE S256、授权同意页面、轮换刷新令牌）。服务会：

• 对没有凭据的请求返回 401，并附带 WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource/mcp", scope="mcp"；
• 在 /.well-known/oauth-protected-resource/mcp 和 /.well-known/oauth-protected-resource 提供 RFC 9728 元数据，并在 /.well-known/oauth-authorization-server 转发仪表板的 RFC 8414 元数据；
• 使用仪表板的内部令牌检查端点（共享密钥）验证每个访问令牌，将有效结果缓存至多 OAUTH_CACHE_SECONDS（30）秒，将无效结果缓存 5 秒，并且只接受受众为 MCP_PUBLIC_URL 的令牌；
• 使用令牌所关联账户的密钥调用 API。密钥不会传到客户端。无效或已撤销的令牌会返回 401 和 error="invalid_token"；如果无法连接到仪表板，则会返回 503 和 Retry-After，以便客户端保留其令牌。

环境（HTTP 模式）

变量	默认值	描述
PORT、HOST	3333、127.0.0.1	监听地址（Docker 镜像使用 3000、0.0.0.0）
TWITTRAPI_BASE_URL	https://api.twittrapi.com	工具调用的网关
TWITTRAPI_RESPONSE_FORMAT	simple	工具结果的默认格式
MCP_PUBLIC_URL	–	/mcp 的公开 URL，例如 https://mcp.twittrapi.com/mcp。令牌受众。
OAUTH_ISSUER	–	授权服务器，例如 https://app.twittrapi.com
OAUTH_INTROSPECTION_SECRET	–	与仪表板共用的密钥（至少 32 个字符）。设置这三项后，OAuth 即启用。
OAUTH_INTROSPECTION_URL	$OAUTH_ISSUER/api/oauth/introspect	introspection 端点的内部 URL
OAUTH_METADATA_URL	$OAUTH_ISSUER/.well-known/oauth-authorization-server	获取转发元数据的位置
OAUTH_CACHE_SECONDS	30	有效令牌的缓存时间（最多 300 秒）。吊销会在此时间内生效。
MAX_CONCURRENCY_PER_KEY	8	每个密钥和实例同时处理的请求数；超出时返回 429，并附带 Retry-After: 1。设为 0 可关闭此限制。
MAX_BODY_BYTES	262144	请求正文超过此大小时返回 413
REQUEST_TIMEOUT_MS	90000	请求运行时间超过此值时返回 504
ALLOWED_ORIGINS	–	浏览器客户端的逗号分隔 Origin 允许列表（防止 DNS 重绑定）
TRUST_PROXY	–	设为 1 可记录来自 X-Forwarded-For 的客户端 IP
LOG_LEVEL	info	debug、info、warn、error

日志以 JSON 行的形式输出到 stdout，每个请求一行：请求 ID、客户端 IP、认证类型 （api_key、rapidapi、oauth、none）、哈希后的密钥 ID（k_ + 12 个十六进制字符）、OAuth 客户端 和账户 ID、JSON-RPC 方法、工具名称、状态和耗时。绝不会记录密钥和令牌。

Docker / Coolify

docker build -t twittrapi-mcp .
docker run -p 3000:3000 -e MCP_PUBLIC_URL=... -e OAUTH_ISSUER=... -e OAUTH_INTROSPECTION_SECRET=... twittrapi-mcp

在 Coolify 中：选择 Dockerfile 构建包，端口设为 3000，健康检查路径设为 /health，域名设为 mcp.twittrapi.com，并配置上述变量。如果两者运行在同一台服务器上，请将 OAUTH_INTROSPECTION_URL 设为仪表板的 内部地址。

开发

npm install
npm run build
npm test

npm test 会先进行构建，然后运行单元测试、协议测试（通过 stdio 和 HTTP 启动服务，并使用本地模拟 API），以及托管模式测试（针对伪造的仪表板测试 OAuth 挑战和元数据、令牌 introspection 和缓存、受众检查、限制及日志脱敏）。

若要添加或修改工具，请编辑 src/endpoints.ts。每个条目都包含名称、描述、API 路径和 zod 参数架构。每个工具还会获得 max_chars，以及 format，除非该条目设置了 rawOnly。 条目可以设置 simplify 函数，以进一步调整解析后的 JSON；目前没有条目使用此函数。账户工具位于 src/actions.ts。

使用 MCP Inspector 交互式试用服务：

npx @modelcontextprotocol/inspector -e TWITTRAPI_API_KEY=your-key node dist/index.js

支持

如有疑问、发现错误或需要提高速率限制，请发送邮件至 [email protected]，或在此代码库中提交问题。服务状态：twittrapi.com/status。新闻和变更：TwittrAPI Telegram 频道（链接见网站）。

许可证

MIT