X-MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@X-MCP search for tweets about open source"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
X-MCP
一个基于 Node.js 的 X/Twitter MCP Server,提供用户资料查询、推文搜索、推文详情获取、单条媒体下载、批量媒体下载等能力。
当前工具集:
x_get_user_profilex_get_tweetsx_search_tweetsx_get_tweet_detailx_download_mediax_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.txtcookies.txt.bak-*.env
这些文件都已经加入 .gitignore,不会上传到远端仓库。
安装
npm install准备认证信息
项目支持两种方式提供登录态,优先级如下:
环境变量
X_COOKIE项目根目录下的
cookies.txt
方式一:使用环境变量
复制示例文件:
cp .env.example .env把浏览器里的 Cookie 粘进去:
X_COOKIE=auth_token=xxx; ct0=xxx; ...方式二:使用 cookies.txt
把浏览器导出的 Netscape Cookie 文件保存为项目根目录的 cookies.txt。
代码会自动读取:
auth_tokenct0
这两个字段缺一不可。
可选环境变量
支持的环境变量如下:
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.txtX_BEARER_TOKEN: 可选,当前默认走 X Web 接口DOWNLOAD_DIR: 下载目录,默认./downloadsHTTP_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注意:
这是
stdioMCP Server,不会监听 HTTP 端口正常用法是由 MCP Host 拉起该进程
在 Claude Desktop 本地安装
1. 先构建 MCP
npm install
npm run build确认构建产物存在:
ls dist/index.js2. 找到 Claude Desktop 配置文件
常见路径:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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建议直接用nodeargs指向本项目的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 build2. 编辑 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 builddist/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
获取用户最新推文。
参数:
usernamecountinclude_retweets
x_search_tweets
搜索推文。
参数:
querycount
x_get_tweet_detail
获取单条推文详情。
参数:
tweet_url
x_download_media
下载单条推文中的媒体。
参数:
tweet_urlmedia_type:all/photo/video/gif
x_download_all_media
扫描最近若干条推文并下载其中媒体。
参数:
usernamecountmedia_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_PROXYct0和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 devGit 远端
推荐远端:
git remote add origin https://github.com/mhqamx/X-MCP.git如果已存在远端则更新:
git remote set-url origin https://github.com/mhqamx/X-MCP.gitAvailable Tools
6 toolsx_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
Scored across 6 tools
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.
All tools follow the consistent 'x_' prefix and snake_case verb_noun pattern (e.g., x_get_tweets, x_download_media), making them predictable.
Six tools is well-scoped for a social media read/media-download server – not too few nor too many.
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
Related MCP Connectors
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Official MCP server for twitterapis.com. Twitter/X search, users, DMs, Grok, monitoring and writes.
Official twitterapi.io hosted MCP: Twitter/X tweets, users, followers, trends. OAuth or API key.
Hosted MCP server from TwitterAPI.io that gives AI agents read-only access to Twitter/X data. 12 tools: tweet search with X operators, user profiles, a user's latest tweets, followers and followings, replies, quotes, retweeters, mentions and trends. Connect at https://mcp.twitterapi.io/mcp with a TwitterAPI.io API key or account sign-in; usage is paid per result returned. Separately, TwitterAPI.io also offers x402 pay-per-call HTTP endpoints (tweet search, user info, a user's latest tweets) paid in USDC on Base or Solana with no account or API key; see https://docs.twitterapi.io/x402-pay-per-call. The MCP server itself uses an API key or sign-in.
Related MCP Servers
- AlicenseCqualityDmaintenanceAn 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.28MIT
- FlicenseAqualityDmaintenanceAn MCP server for interacting with X/Twitter, enabling posting tweets, searching, user info, timeline, liking, retweeting, and deleting tweets.78 npm1-
- AlicenseAqualityDmaintenanceA minimal MCP server for posting tweets to X (Twitter) via API v2, supporting tweet creation, replies, and quote tweets.119 npmMIT
- AlicenseAqualityBmaintenanceMCP server to read X (Twitter) posts, threads, replies, quotes, and search using your own logged-in session, no API key required.8206 PyPI4MIT