X-MCP

一个基于 Node.js 的 X/Twitter MCP Server，提供用户资料查询、推文搜索、推文详情获取、单条媒体下载、批量媒体下载等能力。

当前工具集：

• x_get_user_profile
• x_get_tweets
• x_search_tweets
• x_get_tweet_detail
• x_download_media
• x_download_all_media

功能说明

• 通过 X Web GraphQL 接口获取用户资料和时间线
• 支持按关键词搜索推文
• 支持下载推文中的图片、视频、GIF
• 支持本地批量下载 /media 时间线中的媒体
• 兼容 stdio 方式挂载到 MCP Host

环境要求

• Node.js 20+
• npm 10+
• 可访问 x.com
• 一个可用的 X 登录态 Cookie

建议环境：

• Node.js 22 LTS
• 如本机访问 X 需要代理，配置 HTTP_PROXY / HTTPS_PROXY

目录说明

• src/: TypeScript 源码
• dist/: 构建产物
• downloads/: 下载的媒体文件
• cookies.txt: Netscape 格式 Cookie 文件
• .env.example: 环境变量示例

注意：

• downloads/
• cookies.txt
• cookies.txt.bak-*
• .env

这些文件都已经加入 .gitignore，不会上传到远端仓库。

安装

npm install

准备认证信息

项目支持两种方式提供登录态，优先级如下：

1. 环境变量 X_COOKIE
2. 项目根目录下的 cookies.txt

方式一：使用环境变量

复制示例文件：

cp .env.example .env

把浏览器里的 Cookie 粘进去：

X_COOKIE=auth_token=xxx; ct0=xxx; ...

方式二：使用 cookies.txt

把浏览器导出的 Netscape Cookie 文件保存为项目根目录的 cookies.txt。

代码会自动读取：

• auth_token
• ct0

这两个字段缺一不可。

可选环境变量

支持的环境变量如下：

X_COOKIE=auth_token=xxx; ct0=xxx; ...
X_BEARER_TOKEN=
DOWNLOAD_DIR=./downloads
HTTP_TIMEOUT=30000
REQUEST_DELAY=2000
DEBUG=true
HTTP_PROXY=http://127.0.0.1:7897
HTTPS_PROXY=http://127.0.0.1:7897
NODE_USE_ENV_PROXY=1

说明：

• X_COOKIE: 必填，除非你使用 cookies.txt
• X_BEARER_TOKEN: 可选，当前默认走 X Web 接口
• DOWNLOAD_DIR: 下载目录，默认 ./downloads
• HTTP_TIMEOUT: 请求超时，毫秒
• REQUEST_DELAY: 拉取时间线时的请求间隔
• DEBUG: 打开调试日志
• HTTP_PROXY / HTTPS_PROXY: 访问 X 所需代理
• NODE_USE_ENV_PROXY=1: 让 Node fetch 使用代理环境变量

本地开发

直接以 TypeScript 运行：

npm run dev

等价命令：

npx tsx src/index.ts

启动成功后会在标准错误输出看到：

X Scraper MCP Server 已启动 (stdio 模式)

本地构建与启动

构建：

npm run build

构建后用 Node 启动：

npm run start

等价命令：

node dist/index.js

注意：

• 这是 stdio MCP Server，不会监听 HTTP 端口
• 正常用法是由 MCP Host 拉起该进程

在 Claude Desktop 本地安装

1. 先构建 MCP

npm install
npm run build

确认构建产物存在：

ls dist/index.js

2. 找到 Claude Desktop 配置文件

常见路径：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

如果文件不存在，可以手动创建。

3. 添加本地 MCP 配置

把下面这段加入 claude_desktop_config.json：

{
  "mcpServers": {
    "x-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/x-mcp/dist/index.js"
      ],
      "env": {
        "X_COOKIE": "auth_token=xxx; ct0=xxx; ...",
        "HTTP_PROXY": "http://127.0.0.1:7897",
        "HTTPS_PROXY": "http://127.0.0.1:7897",
        "NODE_USE_ENV_PROXY": "1"
      }
    }
  }
}

说明：

• command 建议直接用 node
• args 指向本项目的 dist/index.js
• 如果你不想把 Cookie 放进配置文件，可以删除 X_COOKIE，改为在项目根目录放 cookies.txt
• 如果本机访问 x.com 需要代理，把 HTTP_PROXY / HTTPS_PROXY / NODE_USE_ENV_PROXY 一起带上

4. 重启 Claude Desktop

重启后，Claude Desktop 会自动拉起这个本地 MCP Server。

如果接入正常，终端手动运行时会看到：

X Scraper MCP Server 已启动 (stdio 模式)

在 Codex 本地安装

Codex 这边用的是 ~/.codex/config.toml。

1. 先构建 MCP

npm install
npm run build

2. 编辑 Codex 配置

打开：

~/.codex/config.toml

加入下面这段：

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

[mcp_servers.x-mcp.env]
X_COOKIE = "auth_token=xxx; ct0=xxx; ..."
HTTP_PROXY = "http://127.0.0.1:7897"
HTTPS_PROXY = "http://127.0.0.1:7897"
NODE_USE_ENV_PROXY = "1"

如果你的 Node 版本支持 --use-env-proxy，也可以把 args 改成：

args = ["--use-env-proxy", "/absolute/path/to/x-mcp/dist/index.js"]

如果你不想在配置文件里写 Cookie，也可以删掉 X_COOKIE，改为在项目根目录提供 cookies.txt。

3. 可选：用 Codex 命令直接添加

如果本机 codex 命令可用，也可以直接执行：

codex mcp add x-mcp -- node /absolute/path/to/x-mcp/dist/index.js

执行完后，再去 ~/.codex/config.toml 里补环境变量。

4. 重启 Codex

重启后新的会话里就能看到 x-mcp 工具。

MCP 挂载排查

如果 Claude 或 Codex 挂载后不可用，优先检查：

• 是否先执行了 npm run build
• dist/index.js 路径是否写对
• X_COOKIE 或 cookies.txt 是否有效
• 本机是否需要代理访问 x.com
• 是否重启了 Claude Desktop 或 Codex

常用命令

安装依赖：

npm install

开发模式启动：

npm run dev

构建：

npm run build

生产启动：

npm run start

下载某账号 /media 时间线前 50 个媒体文件：

npx tsx src/download-user-media.ts example_user 50

检查 /media 时间线分页结构：

npx tsx src/inspect-user-media.ts example_user

工具能力

x_get_user_profile

获取用户资料。

参数：

• username: 用户名，不带 @

x_get_tweets

获取用户最新推文。

参数：

• username
• count
• include_retweets

x_search_tweets

搜索推文。

参数：

• query
• count

x_get_tweet_detail

获取单条推文详情。

参数：

• tweet_url

x_download_media

下载单条推文中的媒体。

参数：

• tweet_url
• media_type: all / photo / video / gif

x_download_all_media

扫描最近若干条推文并下载其中媒体。

参数：

• username
• count
• media_type

常见问题

1. 报 HTTP 404: Query not found

X Web GraphQL 的 queryId 会变化。当前实现已经加入动态发现机制，但如果再次失效，需要重新检查前端 bundle 中的最新操作 ID。

2. 启动了但 Host 里看不到工具

检查：

• MCP Host 配置里的 command / args 是否正确
• dist/index.js 是否存在
• 是否先执行了 npm run build
• 启动命令是否能在终端单独运行

3. 下载失败或超时

检查：

• Cookie 是否有效
• 本机代理是否可访问 x.com
• 是否设置了 HTTP_PROXY / HTTPS_PROXY
• ct0 和 auth_token 是否都存在

本地启动排查

手工启动：

npm run dev

如果需要代理：

HTTP_PROXY=http://127.0.0.1:7897 \
HTTPS_PROXY=http://127.0.0.1:7897 \
NODE_USE_ENV_PROXY=1 \
npm run dev

Git 远端

推荐远端：

git remote add origin https://github.com/mhqamx/X-MCP.git

如果已存在远端则更新：

git remote set-url origin https://github.com/mhqamx/X-MCP.git