x-mcp-ai

x-mcp-ai — X（Twitter）MCP 服务

一个 MCP 服务，可将 X（Twitter）API v2 提供给 MCP 客户端——Claude Code、Claude Desktop、VS Code、Cursor，或任何兼容 MCP 的 Agent——作为 一组精选的类型化工具，由双轴策略模型控制，并考虑了 2026 年按使用量付费的定价，因此 Agent 绝不会在不知情的情况下超支。

状态：1.0 之前，正在积极开发中，已在 npm 上以 x-mcp-ai 发布（当前版本为 0.8.0，通过 CI 发布并附带 npm provenance）。项目处于 0.x 阶段时请固定具体版本 （设置）。目前已注册 12 个包中的 41 个工具；完整设计的 功能范围见 docs/03-tool-catalog.md，且已全部实现。 在 1.0.0 发布前，公共 API 不稳定。

目录：快速演示 · 功能 · 要求 · 设置 · 配置凭据 · 费用 · 运行 / 调试 · 开发 · 工具 · 资源 · 提示词 · 项目结构 · 安全说明 · 数据处理 · 文档 · 支持 · 商标

快速演示

将服务接入 MCP 客户端后，你可以用自然语言驱动它，由模型选择工具。以下是三个典型请求：

// 1. Read (default read-only preset — no writes possible)
// "What are people saying about the Model Context Protocol this week?"
{
  "tool": "x_search_recent",
  "arguments": { "query": "\"model context protocol\" -is:retweet lang:en", "max_results": 25 }
}

// 2. Engage (requires the `engage` preset or an explicit write:engagement allow)
// "Like that launch post for me."
{
  "tool": "x_like_set",
  "arguments": { "post_id": "1899…", "action": "like" }
}

// 3. Publish (requires the `publish` preset or write:content)
// "Post: 'Shipping x-mcp-ai today.' — mind the cost."
// Every result carries cost_usd + session_total_usd; a URL in the text raises the price 13×.
{
  "tool": "x_post_create",
  "arguments": { "text": "Shipping x-mcp-ai today." }
}

功能

• 12 个软件包共提供 41 个工具，涵盖 X API v2——读取帖子、用户和时间线， 搜索（近期和完整归档）、互动、发布、管理列表、上传媒体、遍历社交关系图，以及在明确选择加入后读取和发送私信。
• 双轴策略模型（operation:domain），提供五种预设——read-only（默认）、 engage、publish、manage、full。写入操作默认关闭；按单元格计算，拒绝优先于允许，允许优先于预设。私信单元格采用双重锁定：read:dm/write:dm 不属于任何预设，甚至不属于 full。
• 内置成本监控。 自 2026-02-06 起，X API v2 按使用量付费。每个结果都会报告自身的 cost_usd 和持续累加的 session_total_usd；运维人员设置的 X_MCP_CREDIT_BUDGET 配合 X_MCP_BUDGET_MODE=hard，会拒绝超出预算的调用，模型无法提高上限。
• 两种身份验证模式——OAuth 2.0 PKCE 用户上下文（主要模式，支持轮换刷新令牌和单航班刷新）以及仅用于只读部署的仅应用 Bearer 令牌。
• 安全优先的默认设置——按主机限定的 Authorization 标头、携带令牌的请求绝不跟随重定向、使用 O_NOFOLLOW/O_EXCL 写入权限为 0600 的令牌文件、为返回的文本标记不可信内容，以及在真实路径限定的 X_MCP_MEDIA_DIR 之外默认拒绝媒体上传。
• 类型化故障。 11 种错误类别，每种都包含 retryable 和 fix: "agent" | "operator"，以便模型重试可重试的错误，并升级处理不可重试的错误。
• 结构化输出。 每个工具都会声明 JSON-Schema outputSchema，并在文本块之外返回 structuredContent。
• 按可用性类别进行门控、实时跟踪各端点的速率限制（包括帖子创建的 24 小时应用上限）、游标分页，以及紧凑的结果呈现。

要求

• Node.js >= 22（参见 .nvmrc）。
• 一个 X 开发者账号和应用，并配备 OAuth 2.0 客户端（Client ID；仅机密客户端需要 Client Secret）。仅应用模式则需要 Bearer 令牌。
• 预付 X API 额度——API 按读取和写入分别计费（参见费用）。

设置

推荐的安装方式是使用已发布的软件包；项目处于 0.x 阶段时，请固定到精确版本——无需克隆或构建：

npx -y [email protected] doctor   # sanity check; makes no billable calls

然后将 MCP 客户端指向该软件包：

// claude_desktop_config.json (Claude Desktop) / .mcp.json (Claude Code) / .cursor/mcp.json
{
  "mcpServers": {
    "x": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "X_MCP_AUTH_MODE": "oauth2",
        "X_MCP_CLIENT_ID": "your-oauth2-client-id",
        "X_MCP_POLICY": "read-only",
        "X_MCP_CREDIT_BUDGET": "5.00",
        "X_MCP_BUDGET_MODE": "hard"
      }
    }
  }
}

要从本地检出版本运行？请使用 "command": "node"，并设置 "args": ["/abs/path/to/x-mcp/build/src/index.js"]，以及相同的 env 映射。

通过命令行使用 Claude Code：

claude mcp add x --env X_MCP_POLICY=read-only -- npx -y [email protected]

各客户端的说明——Claude Desktop、Claude Code、VS Code（.vscode/mcp.json）、 Cursor 和 MCP Inspector——请参见 docs/10-operator-guide.md §4，其中还介绍了 authorize 流程和可直接使用的环境变量配置示例。

从源代码构建（开发）

仍全面支持这种方式——构建入口点，并使用 node 而不是 npx 启动：

git clone https://github.com/IvanBBaev/x-mcp.git
cd x-mcp
npm ci
npm run build          # tsc → build/src/index.js
node build/src/index.js doctor   # sanity check; makes no billable calls

配置凭据

服务端绝不会交互式提示输入；所有配置均通过环境变量提供 （规范表格：docs/02-architecture.md §4；入门参考： .env.example）。

身份验证模式（X_MCP_AUTH_MODE）：

• oauth2 （默认）——使用 PKCE 的 OAuth 2.0。通过 authorize 子命令运行一次性授权流程；令牌存储在 X_MCP_TOKEN_FILE 中，并会自动刷新。
• app-only——仅应用 Bearer 令牌（X_MCP_BEARER_TOKEN）；仅限读取端点，不提供用户上下文。

X_MCP_AUTH_MODE=oauth2 X_MCP_CLIENT_ID=… node build/src/index.js authorize

环境变量

变量	默认值	机密	用途
X_MCP_AUTH_MODE	oauth2		oauth2 | app-only。
X_MCP_CLIENT_ID			OAuth 2.0 客户端 ID（authorize 和刷新时必需）。
X_MCP_CLIENT_SECRET		✅	OAuth 2.0 客户端密钥（仅限机密客户端）。
X_MCP_BEARER_TOKEN		✅	仅应用 Bearer 令牌；仅在使用 app-only 时有效。
X_MCP_TOKEN_FILE	由操作系统解析		轮换 OAuth 2.0 令牌存储的路径（会展开 ~）。
X_MCP_TOKEN_KEYCHAIN	0		1 → 将令牌存储在操作系统钥匙串中（macOS security、Linux secret-tool）。不能与 X_MCP_TOKEN_FILE 同时使用。
X_MCP_POLICY	read-only		预设：read-only | engage | publish | manage | full。
X_MCP_POLICY_ALLOW			要添加的 operation:domain 单元格，以逗号分隔。
X_MCP_POLICY_DENY			要移除的单元格，以逗号分隔（优先级高于允许项和预设）。
X_MCP_HIDE_DENIED	0		1 → 完全从注册中移除被拒绝的工具。
X_MCP_CREDIT_BUDGET			会话支出上限，单位为 USD（例如 5.00）。未设置 = 无上限。
X_MCP_BUDGET_MODE	warn		warn | hard。
X_MCP_AVAILABILITY			要启用的可用性类别，以逗号分隔（pilot、premium-user、enterprise）。
X_MCP_MEDIA_DIR			上传文件必须通过 realpath 确认位于其中的目录（媒体默认拒绝）。
X_MCP_PROFILES_FILE			多账户配置文件。
X_MCP_PROFILE			活动配置文件名称（使用配置文件时必需）。
X_MCP_BASE_URL	https://api.x.com		API 基础 URL；必须是 https:// 且域名为 *.x.com。
X_MCP_ALLOW_INSECURE_BASE_URL	0		1 → 允许非 x.com 的基础 URL（仅限测试）。
X_MCP_TIMEOUT_MS	30000		每个请求的超时时间，单位为毫秒。
X_MCP_LOG_LEVEL	info		silent | error | info | debug。

其他任何 X_MCP_* 变量都会被忽略，并显示启动警告——这就是拼写错误检测器。 每个致命配置错误都会指出出错的变量。

双轴访问策略

每个工具都映射到一个策略单元格——一个 operation:domain 配对。操作权限依次提升： read → write → destructive；域包括 content、user、account、engagement、 social-graph、moderation、dm。预设会解锁 12 个有效单元格中的一组； X_MCP_POLICY_ALLOW 添加单元格，X_MCP_POLICY_DENY 移除单元格，且 拒绝 > 允许 > 预设。

预设	授予权限	可调用工具数
read-only （默认）	所有 read:* 单元格，但不包括 read:dm	21
engage	只读 + write:engagement	26
publish	engage + write:content、write:moderation	32
manage	publish + destructive:content	34
full	所有非 DM 单元格——额外授予 write:social-graph、destructive:social-graph	37

DM 单元格永远不会包含在预设中——即使是 full 也不例外。 必须通过 X_MCP_POLICY_ALLOW 显式授予 read:dm 和 write:dm（此时全部 41 个工具均可调用）。策略错误会刻意隐藏其解锁提示， 其他所有敏感单元格也同样如此。被拒绝的工具仍会注册，但会标注为 (disabled by policy <preset>)，除非 X_MCP_HIDE_DENIED=1。

请注意，manage 仅授予具有破坏性的内容操作权限——关注、静音和屏蔽需要 full，或显式允许 write:social-graph / destructive:social-graph。

成本

唯一的定价模式是按量付费。 X 于 2026-02-06 起为新开发者取消了免费版、基础版和专业版订阅套餐；每次读取和写入都会扣除预付额度。 自 2026-04-16 起，文本中包含 URL 的帖子费用为 $0.20，而不是 $0.015 — 涨至 13 倍。在让 Agent 连接真实账号之前，请设置 X_MCP_CREDIT_BUDGET。

参考费率（经 2026-07-22 验证）：读取帖子约 $0.005/次，查询用户以及读取关注者/正在关注列表约 $0.010/次，读取自身数据约 $0.001/次，DM 事件约 $0.010/次，创建帖子 $0.015（含 URL 时为 $0.20），发送 DM $0.015，创建列表 $0.010，互动写入目前免费。X 还将帖子读取量限制为每月 2,000,000 次。权威费率表见 docs/01-api-landscape.md §3；运营者视角见 docs/10-operator-guide.md §5。

预算针对单个进程，属于建议值，重启后重置，且模型不可变——没有单次调用覆盖选项，也没有可以提高预算的工具。

运行 / 调试

MCP 客户端会为你启动服务。手动运行：

X_MCP_POLICY=read-only node build/src/index.js serve

命令行界面

命令	作用
serve （默认）	通过 stdio 启动 MCP 服务。不带子命令运行也会启动服务。
authorize [--manual] [--port <port>]	执行一次性 OAuth 2.0 PKCE 授权流程并保存令牌文件。
doctor [--connect]	输出解析后的配置、路径/权限检查结果和策略矩阵；不产生计费调用。--connect 会额外发起一次未经身份验证的可达性 GET 请求。

stdout 仅承载 JSON-RPC；诊断信息、警告以及唯一的 x-mcp-ai: fatal: <reason> 启动提示会写入 stderr。针对具体症状的修复方法见 docs/11-troubleshooting.md。

开发

git clone https://github.com/IvanBBaev/x-mcp.git
cd x-mcp
npm ci
npm run build         # tsc → build/
npm run check         # typecheck + lint + format:check + test

其他脚本：npm run typecheck、npm run lint、npm run format / format:check、 npm test、npm run coverage（c8）以及 npm run verify（干净构建 + 覆盖率 + lint + 格式检查）。规范和完整质量门槛见 CONTRIBUTING.md。

工具

目前注册的 41 个工具。“只读”标记表示该工具位于 read:* 策略单元格中——可在默认预设下调用（DM 读取除外：需要明确允许）。 “用户”标记表示 user-only 工具，需要 OAuth 2.0 用户上下文，无法通过仅应用令牌调用。设计的工具范围见 docs/03-tool-catalog.md；每个工具的完整参考资料——包括架构、权限范围、成本类别和可用性——见 docs/reference/tools.md。

下表由工具注册表通过 npm run docs:gen 自动生成。请勿手动编辑： npm run check 会重新生成并比较差异，因此编辑会导致 CI 失败，无法发布。docs/reference/tools.md 同理。 | 软件包 | 工具 | 单元格 | 只读 | 用户 | 描述 | |---|---|---|:--:|:--:|---| | auth | x_auth_status | read:account | ✅ | | 报告当前身份验证模式、已验证用户（用户模式下）、已授予的 OAuth 范围、凭据后端、检测到的可用性以及解析后的策略矩阵。 | | auth | x_rate_limit_status | read:account | ✅ | | 导出进程内的速率限制表——按存储桶（端点类别 × 身份验证上下文）列出每个受跟踪窗口的限制、剩余量、重置时间，以及当前是否已耗尽。 | | posts | x_post_get | read:content | ✅ | | 按数字 ID 或状态 URL 批量获取一条或多条 X（Twitter）帖子（每次调用 1-100 条）。 | | posts | x_post_create | write:content | | ✅ | 创建帖子——文本、可选的 reply_to_id、quote_id、media_ids[]、poll {options[], duration_minutes}、reply_settings。 | | posts | x_post_delete | destructive:content | | ✅ | 按 ID 删除自己的帖子。 | | posts | x_post_hide_reply | write:moderation | | ✅ | 隐藏或取消隐藏对自己帖子的一条回复。 | | users | x_user_get | read:user | ✅ | | 按数字 ID、@handle、不带 @ 的 handle，或特殊值 me（已验证用户）批量获取 X（Twitter）用户资料。 | | search | x_search_recent | read:content | ✅ | | 使用完整的 v2 查询语法（from:、to:、conversation_id:、布尔运算符）搜索过去 7 天的 X（Twitter）帖子。 | | search | x_post_counts_recent | read:content | ✅ | | 返回过去 7 天内 X（Twitter）v2 查询的数量直方图（按时间段统计的帖子数量），粒度可选分钟/小时/天。 | | engagement | x_like_set | write:engagement | | ✅ | 以已验证用户的身份为帖子点赞或取消点赞。 | | engagement | x_repost_set | write:engagement | | ✅ | 以已验证用户的身份转发（转推）帖子，或撤销该转发。 | | engagement | x_bookmark_set | write:engagement | | ✅ | 将帖子添加到已验证用户的书签，或将其移除。 | | engagement | x_bookmarks_list | read:content | ✅ | ✅ | 已验证用户自己的书签，按时间从新到旧排列——x_bookmark_set 的读取部分。 | | timelines | x_timeline_home | read:content | ✅ | ✅ | 按时间倒序读取已验证 X（Twitter）用户的主页时间线（他们关注的账号，最新内容在前）。 | | timelines | x_timeline_mentions | read:content | ✅ | | 读取提及某个 X（Twitter）用户的帖子（默认是已验证用户）。 | | timelines | x_timeline_user | read:content | ✅ | | 按时间从新到旧读取某个 X（Twitter）用户自己的帖子，可选择排除回复和/或转发，并可指定时间范围。 | | graph | x_follow_set | write:social-graph | | ✅ | 以已验证用户的身份关注或取消关注某个用户。 | | graph | x_mute_set | write:social-graph | | ✅ | 以已验证用户的身份屏蔽或取消屏蔽某个用户。 | | graph | x_block_set | destructive:social-graph | | ✅ | 以已验证用户的身份拉黑或取消拉黑某个用户。 | | graph | x_followers_list | read:social-graph | ✅ | | 列出关注某个 X（Twitter）用户的账号。 | | graph | x_following_list | read:social-graph | ✅ | | 列出某个 X（Twitter）用户关注的账号。 | | graph | x_user_search | read:user | ✅ | | 按关键词搜索 X（Twitter）用户资料（名称、handle、简介）。 | | lists | x_list_create | write:content | | ✅ | 创建由已验证用户拥有的列表。 | | lists | x_list_update | write:content | | ✅ | 更新已验证用户自己的列表元数据——name、description 和/或 private。 | | lists | x_list_delete | destructive:content | | ✅ | 永久删除已验证用户自己的列表。 | | lists | x_list_get | read:content | ✅ | | 读取一个列表的元数据——名称、描述、隐私设置、成员和关注者数量，以及所有者 handle。 | | lists | x_lists_owned | read:content | ✅ | | 列出某个用户拥有的列表（默认是已验证用户）。 | | lists | x_list_member_set | write:content | | ✅ | 将某个用户添加到已验证用户自己的列表，或将其移除——每次调用仅处理一个用户。 | | lists | x_list_members | read:content | ✅ | | 列出某个列表的成员。 | | lists | x_list_timeline | read:content | ✅ | | 获取列表时间线中的帖子（其成员发布的近期帖子）。 | | lists | x_list_follow_set | write:engagement | | ✅ | 以已验证用户的身份关注某个列表，或取消关注。 | | lists | x_list_pin_set | write:engagement | | ✅ | 在已验证用户的列表视图中置顶某个列表，或取消置顶。 | | media | x_media_upload | write:content | | ✅ | 通过分块式 v2 流程上传本地图片、GIF 或视频，并返回可附加到 x_post_create 的 media_id。 | | media | x_media_status | read:content | ✅ | ✅ | 检查已上传媒体的异步处理状态，需提供 media_id。 | | dm | x_dm_events_list | read:dm | ✅ | ✅ | 列出已验证 X（Twitter）用户所有会话中的近期私信事件，按时间从新到旧排列。 | | dm | x_dm_conversation_events_list | read:dm | ✅ | ✅ | 列出某个 X（Twitter）私信会话中的私信事件，按时间从新到旧排列。 | | dm | x_dm_participant_events_list | read:dm | ✅ | ✅ | 列出与某位参与者的一对一 X（Twitter）私信会话中的私信事件，按时间从新到旧排列。 | | dm | x_dm_send | write:dm | | ✅ | 向唯一一个目标发送 X（Twitter）私信：现有会话（conversation_id）或某个用户（participant）；如有需要，将创建一对一会话。 | | archive | x_search_archive | read:content | ✅ | | 使用完整的 v2 查询语法（from:、to:、conversation_id:、布尔运算符）搜索 X（Twitter）自 2006 年以来的完整存档。 | | archive | x_post_counts_archive | read:content | ✅ | | 返回 X（Twitter）v2 查询在自 2006 年以来的完整存档中的数量直方图（按时间段统计的帖子数量），粒度可选分钟/小时/天。 | | usage | x_usage_get | read:account | ✅ | | 报告当前计费周期的帖子读取用量与项目月度上限的对比情况（可选按日和按应用细分），并附上本次会话的本地额度支出估算。 | DM 读取仅返回 ID、时间戳和参与者；如需读取消息正文，必须在调用时显式设置 include_text: true。

工具包

工具包	涵盖内容
auth	身份验证上下文和限流窗口。
usage	平台读取配额消耗和本地会话支出估算。
posts	创建、读取和删除帖子。
search	搜索近期帖子并统计数量。
archive	搜索完整存档并统计数量。
timelines	主页、提及和用户时间线。
engagement	点赞、转发和书签。
users	查找用户。
graph	搜索个人资料、关注／静音／屏蔽，以及关注者和正在关注列表。
lists	列表的完整生命周期、成员管理、时间线、关注和置顶。
media	分块上传媒体及查询状态。
dm	读取和发送私信（双重锁定）。

资源

MCP 资源已列入计划——将解析后的身份验证上下文和实时限流表作为可寻址资源只读公开。尚未发布。

提示词

MCP 提示词已列入计划——为常见工作流提供引导模板（例如，兼顾成本的发帖、受众研究）。尚未发布。

项目结构

采用端口与适配器架构；模块布局固定，详见 docs/02-architecture.md §3：

src/
├── index.ts            # composition root + stdio wiring
├── core/               # config, policy, budget, errors, ports, tooldef,
│                       #   registry, render, resolve, paginate, sanitize
├── api/                # http, ratelimit, errors, oauth2/, endpoints/
├── tools/              # one module per package (posts, search, graph, …)
├── mcp/                # compose, server, schema, structured, gates, session
└── cli/                # dispatch, authorize, doctor

依赖规则：tools → core + api/endpoints、api → core、mcp → tools + core、 cli → core + api。core 中的任何内容都不会向外依赖或执行 I/O。

安全说明

以下为摘要；完整威胁模型和运营者清单请参阅 SECURITY.md 和 docs/04-security.md。

• 按主机限定身份验证。 Authorization 标头仅会附加到配置的 API 来源；携带令牌的请求绝不跟随重定向（防止混淆代理问题）。 忽略代理环境变量。
• 加固令牌文件。 文件以 0600 权限和 O_NOFOLLOW/O_EXCL 标志写入；令牌刷新采用单飞机制，并在锁内重新加载，遇到竞态时会安全失败。
• 不可信内容。 返回给模型的帖子／用户／DM 文本会标记为不可信。 标记并非语义过滤器——防范提示词注入的真正控制措施是策略模型。
• 不提供提权方法。 对敏感单元（*:dm、destructive:*、*:social-graph）的拒绝会指出被阻止的单元，但绝不会说明可解除限制的变量，因此模型无法向你转述提权方法。
• 媒体默认拒绝。 除非文件的 realpath 位于 X_MCP_MEDIA_DIR 内，否则拒绝上传。
• 成本不可由模型更改。 会话额度由运营者设定；模型无法提高或停用额度。
• 供应链：固定精确版本。 未固定版本的 npx -y x-mcp-ai 会在每次客户端冷启动时执行最新发布的版本——而运行进程持有你的令牌。发布版本通过 CI 发布，并带有 npm provenance。npm 包名为 x-mcp-ai；x-mcp 仅为仓库名称。

数据处理

完整声明：docs/12-privacy.md。

• 不会向外发送任何数据。 无遥测、无分析、无更新检查。该项目不运行任何服务；唯一的出站目标是你配置的基础 URL 上的 X API。
• 凭据保留在本地。 客户端 ID／密钥和 bearer token 位于进程环境中；OAuth 令牌保存在你设备上权限为 0600 的文件中。工具不会返回任何凭据，doctor 会对其进行遮蔽。
• 成本遥测仅限本地。 支出计数器仅在进程内存中，按进程统计，只报告给调用模型，不会发送到其他地方。
• 你读取的内容会从 X 传到你的模型。 工具获取的帖子、个人资料和 DM 事件会返回给你的 MCP 客户端，因此会到达其模型提供商。此服务不会缓存或持久化任何内容。

文档

页面	适用对象
10 — 运维指南	安装、授权、各客户端配置、环境变量配置示例、成本控制。
11 — 故障排查	启动错误、doctor、身份验证/刷新、速率限制、缺少工具。
12 — 隐私与数据处理	数据会发送到哪里、存储哪些数据，以及如何删除。
01 — API 概览	按使用量计费、可用性类别、平台限制。
02 — 架构	模块布局和规范的环境变量表。
03 — 工具目录	设计的工具范围及其分类。
04 — 安全	威胁模型、策略模型、令牌生命周期。

支持

如果这个项目为你节省了时间，欢迎支持：

商标

x-mcp-ai 是一个独立的非官方项目。它与 X Corp 无关联，未获其认可，也未获其赞助。它通过官方公开文档记录的 X API v2 进行交互，不使用任何私有、未公开记录或基于抓取的访问方式。

“X”、“Twitter”及相关名称、徽标和标记均为 X Corp 的商标。本文使用这些商标仅用于指称本软件所交互的对象。本项目依据 MIT License 发布；不授予任何商标权利。