X Use
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 Use show me recent posts from @XDevelopers"
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 Use
A read-only MCP server for the X API v2, using the official xurl OAuth client as the only credential source.
X Use exposes structured tools for posts, users, timelines, search, conversations, media metadata, and account/credit status. It does not manage a second token store and does not expose posting, reply, DM, follow, like, bookmark, delete, or media-upload tools.
中文说明见下方。
Features
Tool | Purpose | X API |
| Read a post by URL or ID, including author/media/references |
|
| Look up a user by username or numeric ID |
|
| Read a user's recent posts with pagination |
|
| Recent or full-archive search |
|
| Resolve | Post lookup + Search |
| Read media metadata by media key |
|
| Verify authentication and read developer credits |
|
All tool calls return JSON with a stable envelope:
dataandincludes: the relevant upstream X API payloadpagination: mappednext_token,previous_token,newest_id, andoldest_idmeta: tool, endpoint, upstream metadata, andpartial_errorserror.code:unauthenticated,forbidden,rate_limited,not_found,invalid_request, orunknown
Related MCP server: @xcrap/mcp
Requirements
Node.js 20 or newer
Official
xurlwith an authorised OAuth2 userAn X developer App with access to the endpoints you intend to use
Credits/entitlement for the corresponding X API calls
The server reads X through xurl with --auth oauth2. It does not read ~/.xurl/auth.yml, print tokens, or accept access tokens through MCP arguments.
Quick start
git clone https://github.com/felixlark/x-use.git
cd x-use
npm ci
npm testRun directly from the checkout:
X_USE_APP=your-xurl-app \
X_USE_USER=your-x-username \
node bin/x-use-mcp.jsThe process speaks MCP over stdio; it is not intended to be used as a normal HTTP server.
Install for Codex
The supplied installer creates a versioned local installation, atomically switches current, and links the bundled Skill into ~/.agents/skills/x-use.
./scripts/install.shOn macOS the default MCP executable is:
$HOME/Library/Application Support/x-use/current/bin/x-use-mcp.jsOn Linux it is:
$HOME/.local/share/x-use/current/bin/x-use-mcp.jsRegister it with Codex using your own existing xurl app and OAuth2 username:
codex mcp add x-use \
--env X_USE_APP=your-xurl-app \
--env X_USE_USER=your-x-username \
-- "$HOME/Library/Application Support/x-use/current/bin/x-use-mcp.js"Use the Linux path shown above where applicable. Reload or restart the MCP connection after installation.
Configuration
Variable | Required | Meaning |
| Recommended | Registered app name in xurl |
| Recommended | Existing OAuth2 username in xurl |
| No | Path to xurl; defaults to |
| No | Per-command timeout, 1–120 seconds |
| No | Override the installer's application-data directory |
| No | Override the installer's Skill root |
The implementation always requests OAuth2 user context. It never silently falls back to OAuth1, app-only bearer, another user, or another provider.
Example
{
"name": "x_user_posts",
"arguments": {
"user": "@XDevelopers",
"max_results": 5
}
}A successful result contains the X payload plus a pagination view:
{
"ok": true,
"data": ["..."],
"includes": {"users": ["..."]},
"pagination": {
"result_count": 5,
"next_token": "opaque-next-token",
"previous_token": null,
"newest_id": "...",
"oldest_id": "..."
},
"meta": {
"tool": "x_user_posts",
"backend": "x_api_v2",
"partial_errors": []
}
}Documentation
API investigation: source-backed capability, auth, pricing, rate-limit, hosted MCP, and XChat notes
Architecture: backend choice, trust boundaries, upgrade and fallback paths
Interfaces and implementation: tool contracts, call flow, envelopes, error mapping, and installer
Safety and boundaries
X Use is deliberately read-only. Write actions require a separate, explicit design and per-action authorization.
An MCP tool's absence is not evidence that an external action is unauthorized or authorized.
X API rate limits, account entitlement, and usage charges remain in force; this project does not buy credits or change billing.
x_mediamay returnforbiddenwhen the developer App is not enrolled in a required Project. Parent-postincludes.mediaremains available throughx_post.XChat is not exposed: encrypted content additionally requires DM scopes, a Chat XDK, and client-held private keys.
Never put tokens, cookies, XChat PINs, private keys, or private account data in an issue, pull request, fixture, or log.
Development
npm ci
npm test
npm run check
npm run check:livenpm test is offline and covers parsing, pagination/field mapping, error classification, redaction, MCP tool discovery, resources, and mocked tool calls. npm run check:live performs a small read-only smoke test and therefore uses real X API credits.
中文概览
X Use 是一个只读的 X API v2 MCP Server。它复用本机官方 xurl 的 OAuth2 会话,不保存第二份 token,也不暴露发帖、回复、DM、关注、点赞、书签、删除或媒体上传工具。
七个工具分别覆盖帖子、用户、用户帖子、搜索、会话、媒体元数据和认证/额度状态。返回使用统一的 data、includes、pagination、meta 信封;错误分为 unauthenticated、forbidden、rate_limited、not_found、invalid_request 和 unknown。
安装、Tool 参数、调用链和错误映射见 接口与实现。使用前需要 Node.js 20+、官方 xurl 和对应的 X API 权益;本项目的真实读取 smoke 会消耗实际 API credits。
License
MIT. See LICENSE.
Available Tools
7 toolsx_mediaRead X media metadataARead-onlyIdempotent
Read media metadata by media key. The direct endpoint may be forbidden when the developer App is not enrolled in a Project; the error is returned without fabricating data. Read-only.
Inputs: media_key (required), media_fields.
x_postRead an X postARead-onlyIdempotent
Read one public/visible X post by URL or numeric ID. Returns upstream data, includes, and structured pagination/error envelopes. Read-only.
Inputs: post (required), expansions, poll_fields, post_fields, +3 more.
x_searchSearch X postsARead-onlyIdempotent
Search X posts. scope=recent covers the last 7 days; scope=all requests full-archive search and may be forbidden by account entitlement. Read-only.
Inputs: query (required), scope, end_time, since_id, +11 more.
x_statusCheck X authentication and creditsARead-onlyIdempotent
Check xurl version and safe auth metadata, verify OAuth2 user access, and read the developer credit balance. Does not print tokens or write to X. Read-only.
Inputs: no named parameters.
x_threadRead an X conversationARead-onlyIdempotent
Resolve a post's conversation_id and read posts in that conversation. Recent scope only covers the last 7 days; full scope may be forbidden. Read-only.
Inputs: post (required), scope, expansions, max_results, +6 more.
x_userLook up an X userARead-onlyIdempotent
Look up an X user by @username, username, or numeric user ID. Read-only.
Inputs: user (required), expansions, post_fields, user_fields.
x_user_postsRead a user's recent postsBRead-onlyIdempotent
Read posts authored by an X user. The username is resolved to a user ID first when needed. Read-only.
Inputs: user (required), exclude, end_time, since_id, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool maps to a fairly distinct target: search, single post, user lookup, user timeline, media, thread, and status. The only mild overlaps are x_post vs x_thread (both return posts) and x_search vs x_user_posts (both return post collections), but the descriptions make the boundaries clear.
All tools use a consistent 'x_' prefix with snake_case, keeping them visually grouped and predictable. The only wrinkle is that x_post is a noun-style name that could be misread as a write action, though 'Read-only' in the description resolves it.
Seven tools is a tight, well-scoped set for an X read client, with no redundant entries. Every tool covers a distinct resource path (search, post, user, timeline, media, thread, diagnostics).
Read coverage is solid across posts, users, timelines, threads, and media, plus an auth/credit diagnostic. However, the surface is entirely read-only with no write operations (post, reply, like, repost, follow), and common reads like followers/following lists or engagement metrics are absent, which will limit many agent workflows.
Maintenance
Related MCP Connectors
Read-only public X (Twitter) data: profiles, tweets, threads, followers, search. Pay per result.
Live X/Twitter data: profiles, tweets, search, followers, lists and trends. 29 read-only tools.
X (formerly Twitter): X (formerly Twitter) public and private data API for search, posts (Tweets).
Read public X (Twitter) data and verify follows, reposts, replies and quotes. 14 read-only tools.
141
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables MCP clients to interact with the X (Twitter) API v2 through 41 typed tools for reading, searching, engaging, publishing, and managing content, with policy-based access control and session credit budgets to prevent overspending.4149 npm1MIT

@xcrap/mcpofficial
AlicenseAqualityCmaintenanceProvides read-only access to X (Twitter) data — posts, threads, profiles, timelines, followers, media, and trends — through twelve tools, with no login or API key required.1220 npm1MIT- AlicenseAqualityCmaintenanceEnables read-only research on public X data through tools for posts, threads, profiles, search, trends, collections, and saved-result analysis using free public APIs and optional sessions.8MIT
- AlicenseNot gradedqualityBmaintenanceProvides read-only access to public X (Twitter) data, including profiles, tweets, timelines, threads, followers, and search, for developers and AI agents.1MIT