Twitter/X MCP

Twitter/X MCP

Twitter/X MCP 允许 MCP 客户端读取 X 上的公开帖子、回复和个人资料，也可以搜索 X。它默认使用 Rettiwt，因此无需 X 开发者套餐。如果你有权限，也可以切换到官方 X API。

要求

• Node.js 22.21.0 或更高版本（Node 22 发布系列）是声明支持的运行时。有关 Node 24 的测试和安装限制，请参阅下文。
• 一个 RETTIWT_API_KEY。选择 API 模式时，也可以使用官方 X API 凭据。

Node 24 兼容性

在 Node.js 24.19.0 上，全项目检查和全部五次实时 MCP 工具调用均已通过。CI 也会在 Node 24 上运行全项目检查。

已发布的软件包和 Rettiwt 7.1.4 仍声明 engines.node: "^22.21.0"。因此，在 Node 24 上安装可能会产生 EBADENGINE 警告；启用 engine-strict 时，npm 会拒绝安装。请使用 Node 22.21.0 或更高版本的 Node 22，以便在声明的支持范围内安装。官方支持 Node 24 仍需等待 Rettiwt 发布声明兼容 Node 24 的版本，并相应更新此软件包的 engine 范围。

快速开始

软件包发布后，你的 MCP 客户端无需克隆即可运行：

npx -y @granitebps/twitter-mcp

如果未设置 TWITTER_MODE，服务将选择 Rettiwt。在客户端配置中传入 RETTIWT_API_KEY。

服务使用 stdio。请将 stdout 留作 MCP 通信专用。

从克隆的仓库运行

要开发此服务或直接使用克隆的仓库：

git clone https://github.com/granitebps/twitter-mcp.git
cd twitter-mcp
npm ci
npm run build

将 MCP 客户端指向编译后的入口点：

node /absolute/path/to/twitter-mcp/dist/cli.js

每次更改源代码后都运行 npm run build。请勿将 src 或 npm run dev 用作客户端的 stdio 命令。stdout 上的构建日志可能会损坏 MCP 消息。

客户端配置

每个示例都先使用 npm 软件包，随后给出对应的本地配置。将 /absolute/path/to/twitter-mcp 替换为克隆仓库的路径，并将 your_key_here 替换为你的 Rettiwt 密钥。请勿提交包含密钥的配置文件。

Claude

将 npm 软件包添加到 Claude Code：

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- npx -y @granitebps/twitter-mcp

使用本地构建时：

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- node /absolute/path/to/twitter-mcp/dist/cli.js

Claude Code 默认使用本地范围。要让所有项目都能使用此服务，请在 twitter 前添加 --scope user。

Claude Desktop 从 claude_desktop_config.json 读取相同的服务。编辑文件后请重启应用。

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

使用本地构建时，将 command 和 args 替换为：

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Codex

将 npm 软件包添加到 ~/.codex/config.toml，或添加到可信项目中的 .codex/config.toml：

[mcp_servers.twitter]
command = "npx"
args = ["-y", "@granitebps/twitter-mcp"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

使用本地构建时：

[mcp_servers.twitter]
command = "node"
args = ["/absolute/path/to/twitter-mcp/dist/cli.js"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

编辑文件后请重启 Codex。同一台计算机上的命令行、IDE 扩展和桌面应用共用此配置。

OpenCode

将 npm 软件包添加到 opencode.json 或 opencode.jsonc：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "twitter": {
      "type": "local",
      "command": ["npx", "-y", "@granitebps/twitter-mcp"],
      "enabled": true,
      "environment": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

使用本地构建时，将 command 数组替换为：

{
  "command": ["node", "/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Cursor

将 npm 软件包添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json 以供全局使用：

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

使用本地构建时，将 command 和 args 替换为：

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

提供方

模式	选择方式	凭据	备注
Rettiwt	默认，或 TWITTER_MODE=rettiwt	RETTIWT_API_KEY	不产生 X API 费用。使用非官方内部端点，可能会失效或使账户面临风险。
官方 API	TWITTER_MODE=api	Bearer 令牌或完整的 OAuth 凭据	使用受支持的 X API。访问层级和定价由 X 决定。

Rettiwt 设置

此服务要求 Rettiwt 使用已认证的用户模式。不支持访客模式。

1. 按照 Rettiwt 身份验证说明生成 API 密钥。
2. 将其作为 RETTIWT_API_KEY 存储在 MCP 客户端的环境中。
3. 不设置 TWITTER_MODE 启动服务，或显式设置 TWITTER_MODE=rettiwt。

Rettiwt 密钥包含 X 会话 Cookie，拥有与账户相同的访问权限。请将其视为密码。请勿提交、粘贴到问题中、记录到日志，或将其作为命令行参数传递。密钥仅可用于你拥有或获准访问的账户。

Rettiwt 是非官方的。X 的自动化规则禁止通过非 API 方式自动化操作网站，并警告违规行为可能导致账户被暂停。使用此模式前，请阅读 X 规则。你需自行承担合规和账户风险。

官方 X API 设置

使用 Bearer 令牌：

TWITTER_MODE=api
TWITTER_BEARER_TOKEN=your_bearer_token

或提供完整的 OAuth 凭据：

TWITTER_MODE=api
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_SECRET=your_access_secret

在 X Developer Portal 中创建凭据。API 访问权限和定价由 X 决定，因此选择此模式前请查看当前条款。

配置

变量	必需	含义
TWITTER_MODE	否	默认为 rettiwt，也可设为 api。其他值会导致启动失败。
RETTIWT_API_KEY	Rettiwt 模式	已认证的 Rettiwt 会话密钥。
TWITTER_BEARER_TOKEN	API 模式选项	官方 API Bearer 令牌。
TWITTER_API_KEY	OAuth 选项	OAuth 应用密钥。
TWITTER_API_SECRET	OAuth 选项	OAuth 应用密钥。
TWITTER_ACCESS_TOKEN	OAuth 选项	OAuth 访问令牌。
TWITTER_ACCESS_SECRET	OAuth 选项	OAuth 访问密钥。
TWITTER_REQUEST_TIMEOUT_MS	否	请求时限为 1,000 至 120,000 ms。默认值：30,000。

服务会在启动时拒绝不完整的 OAuth 配置。它会从进程环境中读取凭据，且绝不会通过 get_server_info 返回这些凭据。

工具

工具	输入	结果
get_tweet	tweet_id	一条帖子。接受数字 ID，或 x.com、twitter.com 状态 URL。
get_tweet_replies	tweet_id、可选的 max_results	回复和可用的分页元数据。
get_user_profile	username	一个公开个人资料。接受以 @ 开头的用户名。
search_tweets	query、可选的 max_results	匹配的帖子和可用的分页元数据。搜索运算符取决于提供方。
get_server_info	无	版本、当前提供方、工具、限制和功能。

max_results 默认值为 10，接受 1 到 100 之间的值。成功调用会返回结构化 MCP 内容，以及供旧版客户端使用的 JSON 文本。集合类工具会以 JSON 文本返回条目，并在结构化内容中提供游标和警告。

在 Rettiwt 模式下，如果提供方提供媒体，get_tweet、get_tweet_replies 和 search_tweets 返回的帖子还会包含可选的 media 数组。每个条目包含 id、type（PHOTO、VIDEO 或 GIF）、直接的 url，以及视频预览的可选 thumbnail_url。服务会返回媒体链接，不会下载文件。官方 API 模式目前不会返回附加媒体。

v1 兼容性契约 记录了 1.x 发行系列中稳定的工具、输入、输出和错误行为。

错误

工具故障使用稳定的代码：

• INVALID_INPUT
• AUTH_REQUIRED
• AUTH_FAILED
• NOT_FOUND
• RATE_LIMITED
• UPSTREAM_UNAVAILABLE
• TIMEOUT
• UNSUPPORTED_OPERATION
• INTERNAL_ERROR

错误会注明提供方，并告知客户端重试是否可能成功。错误中不包含凭据或原始上游响应正文。

架构

stdio CLI
  -> validated environment configuration
  -> MCP server and tool handlers
  -> TwitterProvider contract
       -> Rettiwt adapter
       -> official X API adapter

领域架构不依赖任何一个提供方。每个提供方适配器都会映射上游数据、强制执行限制和截止时间，并转换错误。导入 src/index.ts 不会启动服务。

开发

npm ci
npm run check

npm run check 会检查格式、lint、类型、覆盖率、生产构建、npm 包内容，以及干净的 tarball 安装。默认测试套件使用模拟对象，无需 X 凭据。

常用的定向命令：

npm test
npm run typecheck
npm run lint
npm run build
npm run check:package
npm run check:install
npx @modelcontextprotocol/inspector node dist/cli.js

Rettiwt 在线冒烟测试

在线冒烟测试会启动编译后的 stdio 服务，并调用 get_tweet、get_tweet_replies、get_user_profile 和 search_tweets。它会根据所选帖子推导用户名和搜索查询。

RETTIWT_API_KEY=your_key_here \
TWITTER_LIVE_TWEET_ID=1234567890123456789 \
npm run test:live

请选择一条作者个人资料仍然可用的公开帖子。如果缺少任一变量，命令会在启动在线服务或发出网络请求前停止。该测试不会作为 npm run check 或常规 CI 的一部分运行。

发布验证

自动化测试套件涵盖配置、提供方适配器、MCP 调用、编译后的 stdio 入口，以及从 npm tarball 安装。Rettiwt 在线冒烟测试为可选项，不会在常规 CI 中运行。1.0.0 版本的准备过程未进行在线上游验证。

维护者可按照发布指南 执行经批准的标签发布流程，包括 npm、MCP Registry 和 GitHub 发布。在线测试 必须从仓库机密中读取凭据，且不得针对不受信任的拉取请求运行。

故障排除

缺少 Rettiwt 密钥

如果启动时提示 RETTIWT_API_KEY is required in rettiwt mode，请在 MCP 客户端配置中设置密钥。桌面客户端不会自动继承 shell 的 .env 文件。

Rettiwt 身份验证无效

如果看到 Invalid authentication data 或 AUTH_FAILED，请生成新的 Rettiwt 密钥，并确认 X 会话仍然有效。切勿在问题帖中发布失效的密钥。

速率限制

遇到 RATE_LIMITED 时，请等待一段时间再重试，并降低请求频率。如果提供方提供了 retryAfterSeconds，请查看该值。

官方 API 返回 401 或 403

请确认凭据集、应用权限、端点访问权限以及当前的 X API 方案。

Node 引擎警告

请运行 Node.js 22.21.0 或更新的 Node 22 版本，以满足软件包和 Rettiwt 的引擎版本范围。Node 24.19.0 已通过运行时测试，但在 Node 24 上安装时，如果启用了 engine-strict，可能会出现警告或失败；请参阅 Node 24 兼容性。

许可证

ISC