Skip to main content
Glama
X-MCP
by mhqamx

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

Related MCP server: x-mcp

环境要求

  • 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

Available Tools

6 tools
x_download_all_mediaB

批量下载某博主最新推文中的所有图片和视频

Inputs: username (required), count, media_type.

x_download_mediaC

下载指定推文中的图片和视频到本地

Inputs: tweet_url (required), media_type.

x_get_tweet_detailA

获取单条推文的详细信息,包括完整文本、媒体链接、互动数据

Inputs: tweet_url (required).

x_get_tweetsB

获取指定用户的最新推文列表

Inputs: username (required), count, include_retweets.

x_get_user_profileB

获取 X 平台用户的基本信息(头像、简介、粉丝数等)

Inputs: username (required).

x_search_tweetsB

按关键词搜索推文,支持 X 高级搜索语法

Inputs: query (required), count.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct action: user profile, tweet listing, tweet detail, search, media download from user, and media download from tweet. No overlap in functionality.

    Naming Consistency5/5

    All tools follow the consistent 'x_' prefix and snake_case verb_noun pattern (e.g., x_get_tweets, x_download_media), making them predictable.

    Tool Count5/5

    Six tools is well-scoped for a social media read/media-download server – not too few nor too many.

    Completeness3/5

    Covers core read operations (profile, tweets, search, tweet detail) and media download, but lacks write operations like posting, liking, or retweeting, which are common in such APIs.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      An MCP server for accessing the Twitter/X Api45 API, allowing users to retrieve user profiles, timelines, followers, and media. It supports searching communities, jobs, and trends, while also providing tools to monitor live broadcasts and Twitter Spaces.
      28
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      An MCP server for interacting with X/Twitter, enabling posting tweets, searching, user info, timeline, liking, retweeting, and deleting tweets.
      7
      8 npm
      1
      -
    • A
      license
      A
      quality
      D
      maintenance
      A minimal MCP server for posting tweets to X (Twitter) via API v2, supporting tweet creation, replies, and quote tweets.
      1
      19 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server to read X (Twitter) posts, threads, replies, quotes, and search using your own logged-in session, no API key required.
      8
      206 PyPI
      4
      MIT