x-mcp

一个自带主张的 MCP 服务器，用于通过代理运营 X 账号。

它不是 X API 的包装器。它是一个小型操作器，知道 API 不会告诉你的四件事：

1. For You 如何排名 — X 开源算法（xai-org/x-algorithm）中的权重、门槛和过滤器被内置到每个工具中，作为护栏和建议：互关的回复权重 5→20，复制链接分享 20，点赞 0.5；严格 >10 秒视频；≤1 个 @-提及；禁止互动诱饵；原创帖子之间间隔 ≥4 小时；首次点赞会打开站外语料库；粉丝数低于 1000 的冷启动提升；24 小时/48 小时窗口。

2. 按量付费 API 实际允许什么 — 自 2026 年起，X 拒绝未召唤的回复，并从自助服务中移除了关注、点赞和引用帖子。工具会执行所有允许的操作，并把其余操作以一键意图链接交给人工，然后通过 $0.001 的自有读取自动对账人工完成的操作。

3. 每次调用的成本 — 本地账本镜像 X 的按资源定价（含 24 小时去重），强制执行月度预算，并在 $0.20 的“带 URL 发帖”之前提醒你。

4. 业务沉淀了什么 — 一份记录所有互动者（以及该回关谁）的关系账本，一个能学习你最佳时段的内容日历，一份每个会话共享的品牌手册，一个创意管道，以及一个洞察/报告循环，让代理根据自己的数据而非感觉来决策。

基于 MCP TypeScript SDK v2 构建。默认使用 stdio，可选 Streamable HTTP。除 SDK 和 zod 外，零运行时依赖。

工具

资源：x://playbook（规则）、x://boundary（API 允许的操作）、x://handoff（实时人工队列）。提示词：operate（工作循环）。

Related MCP server: X(Twitter) V2 MCP Server

设置

1. 创建应用：前往 https://console.x.com → 启用 OAuth 2.0 → 应用类型选择 Native App（公开，PKCE）或 Automated App/Bot（机密，会提供客户端密钥）→ 添加重定向 URI http://127.0.0.1:8477/callback → 复制 Client ID（如果是机密应用，还要复制密钥）。充值一些额度（按量付费）。

2. 配置 — 环境变量从环境或 ~/.x-mcp/.env 中读取（绝不会从当前目录读取，这样恶意仓库的 .env 就无法重定向你的令牌）：

   cd x-mcp && npm install && npm run build
   mkdir -p ~/.x-mcp/media && cp .env.example ~/.x-mcp/.env   # set X_CLIENT_ID (+ X_CLIENT_SECRET if confidential)

   代理可上传的媒体必须放在 ~/.x-mcp/media 下（或 X_MCP_MEDIA_ROOT 指定的目录）——把你的演示视频放到那里。

3. 登录一次（会打开浏览器，将令牌存储在 ~/.x-mcp/tokens.json，权限模式 0600）：

   node dist/bin.js login

4. 连接到你的代理。

   Hermes（~/.hermes/config.yaml）：

   mcp_servers:
     x:
       command: node
       args: ["/absolute/path/to/x-mcp/dist/bin.js"]
       env:
         X_CLIENT_ID: "…"
         X_CLIENT_SECRET: "…"          # confidential apps only
         X_MCP_MONTHLY_BUDGET_USD: "25"
         X_MCP_REQUIRE_APPROVAL: "true" # default; keep until you have X's AI-reply approval
       timeout: 180

   Claude Code：

   claude mcp add x -e X_CLIENT_ID=… -e X_MCP_REQUIRE_APPROVAL=true -- node /absolute/path/to/x-mcp/dist/bin.js

   使用 HTTP 代替 stdio：X_MCP_HTTP_TOKEN=SECRET node dist/bin.js --http --port 8478 → url: http://127.0.0.1:8478/mcp，请求头 Authorization: Bearer SECRET。始终需要令牌（如果你未设置，会生成并打印一个）；Host/Origin 会与 localhost 进行校验。

5. 运行循环。 让代理使用 operate 提示词（或直接粘贴）。运行 node dist/bin.js queue 查看是否有需要你处理的事项；node dist/bin.js approve --all 执行排队的 API 操作；点击仅限人工操作的意图链接，然后运行 handoff(reconcile)（或让代理来做），这样队列就会自动清空。

6. 把 tick 放到定时器上（每 15 分钟就足够了），这样定时帖子会发出、handoff 会对账、指标会为 insights 生成快照：

   */15 * * * * cd /absolute/path/to/x-mcp && node dist/bin.js tick >> ~/.x-mcp/tick.log 2>&1

   （Hermes 用户：一个调用 schedule(run_due) + handoff(reconcile) + post_performance 的 cron 任务也能达到同样效果。）

配置（环境变量）

它拒绝什么，以及为什么

• 帖子中两个或更多 @-提及 → 会被 X 的实时 LLM 垃圾评分。请把致谢放在回复中。

• “Like if / RT for / tag someone” → SpamHighRecall，没有任何人豁免。

• 视频 ≤10.0s → 视频开头为 0，且该帖子被排除出所有视频语料库。

• 一个帖子同时包含视频和图片 → 失去视频语料库资格。

• 4 小时内的第二个原创帖 → 在共享 slate 中 ×0.625；冷启动提升每次请求只挑一个帖子。

• 相同的回复文本两次 → 复制粘贴聚类。

• 回复一个没有 @‑提及你的帖 → X 会拒绝；你会得到一个 intent 链接。

• 任何超出当月预算的支出。

一切软性限制都可以用 force: true 覆盖——它总是把操作转入人工审批队列；媒体根目录、预算和 X 自身的限制无法覆盖。

安全问题（简略）

• 令牌/状态存放在 ~/.x-mcp（0700 目录、0600 文件）；服务器和 x-mcp approve CLI 可安全地共享它们（写入前重载，绝不覆盖更新的令牌集）。

• 代理不能读取任意文件：media_paths 必须解析到媒体根目录之下；ID 被校验为数字雪花 ID（不允许借 ../ 进行路径走私至其他端点）。

• 不可逆或对策略敏感的操作（delete_post、任何 force、DM、审批模式）都需要在 CLI 中人工点击确认。delete_post 只接受服务器确认属于你的帖子。

• 工具输出中的第三方文本只是数据，不是指令。HTTP 模式需要令牌，并会校验 Host/Origin。

你应该阅读的政策说明

• X 的自动化规则（2026 年 4 月）要求 AI 回复机器人必须先获得书面批准，每个用户交互最多一条自动回复，不得重复发帖，不得批量关注/点赞/私信，并且必须带有 Automated 账号标签（设置 → 你的账户 → 账户信息 → 自动化）。本服务器执行机械部分；批准与标签需要你自己去申请与设置。

• 你提交的开发者协议使用场景应当描述代理的实际行为（发帖、读取自己的数据、进行垂直研究）。

开发

npm test          # rules engine + full server through an in-memory MCP client against a mock X API
npm run typecheck
npm run build

来源：X 文档（docs.x.com，2026-08-06 读取：pricing、publish 接口限制、media v2、OAuth 2.0）以及 enum实现（home-mixer/params/param.rs、scorers/、filters/、visibility-filtering/、phoenix/、grox/）。参见 docs/FOR_YOU_PLAYBOOK.md 中的完整研究。

MIT.