Twitter/X MCP

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

要求

• Node.js 22.21.0 或更高版本，且必须属于 Node 22 发布线。当前 Rettiwt 版本不支持 Node 23 或更高版本。

• 一个 RETTIWT_API_KEY。当选择 API 模式时，官方 X API 凭据也可使用。

Related MCP server: X MCP Server

快速开始

包发布后，你的 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。CLI、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 设置

在此服务器中，Ritti 要求使用已验证的用户模式。访客模式不受支持。

1. 使用 Rettiwt 身份验证说明 生成一个 API 密钥。

2. 将其作为 RETTIWT_API_KEY 存储在 MCP 客户端的环境中。

3. 客户端启动服务器时，不要带 TWITTER_MODE，或者显式设置为 TWITTER_MODE=rettiwt。

Rettiwt 密钥包含 X 会话 cookie，并且具有与账号相同的访问权限。请像对待密码一样对待它。不要将它提交到代码库、粘贴到 issue 中、写入日志，或作为命令行参数传递。请仅为你拥有或有权限访问的账号使用此密钥。

Rettiwt 是官方服务。X 的 自动化规则 禁止非 API 的网站自动化操作，并警告违规可能导致账号被冻结。使用此模式前，请阅读 X 规则。你需要自行承担遵循规定和账号风险。

官方 X API 设置

使用 Bearer token：

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 中创建凭据。X 控制 API 访问和定价，因此请在选择此模式前查看履行当前条款。

配置

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

工具

max_results 默认为 10，可接受 1 到 100。成功的调用会返回结构化 MCP 内容，以及用于旧版客户端的 JSON 文本。集合类工具将项作为 JSON 文本返回，并将游标和警告放入结构化内容中。

错误

工具失败使用稳定的错误码：

• 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

领域中的 schema 不依赖任何提供方。每个提供方适配器将上游数据映射到统一结构，强制执行限制和期限，并转换错误。只加载 src/index.ts 不会启动服务器。

开发

npm ci
npm run check

npm run check 检查格式、lint、类型、覆盖率、生产构建、npm 包内容以及干净的 tarball 安装。默认测试套件使用 fakes，不需要 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 安装。活跃 Reti instance 测试是可选的，不会在常规 CI 中运行。版本 1.0.0 是在没有实时上游验证的情况下准备的。

维护者可以遵循 release guide 来执行手动 npm、MCP Registry 和 GitHub release 流程。实时测试必须从仓库 secret 读取凭据，并且绝不可在不受信任的 pull request 中运行。

故障排除

缺少 Rettiwt 密钥

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

Rettiwt 认证无效

如果看到 Invalid authentication data 或 AUTH_FAILED，请重新生成一个 Retti 密钥，并检查 X 会话是否仍有效。不要在某个 issue 中发布失败密钥的内容。

速率限制

对于 RATE_LIMITED，请在重试之前等待，并降低请求频率。当 retryAfterSeconds 提供时，请检查该字段。

官方 API 401 或 403

确认凭据设置、应用权限、端点访问权限，以及现有的 X API 计划。

Node engine 警告

请使用 Node.js 22.21.0 或更新版本的 Node 22，注意当前 Rettiwt 依赖不要与 Node 23 或更高版本一起使用。

License

License is ISC.