X Research MCP
This server provides read-only X (Twitter) research tools for public data via MCP.
Search public posts or users (
x_search) with latest/top/media sort, pagination, and compact/full detail.Read a single post, its author thread, replies, quotes, or reposters (
x_post_get).Read public profiles and user content (
x_user_get): profile, posts, replies, media, articles, followers, following.Read public lists/communities (
x_collection_get): info, posts, members (requires session and public-visibility proof).Read trends (
x_trends_get): trending, plus news/sport/entertainment with a session.Analyze saved results (
x_analyze): summary, activity, engagement, link domains, hashtags; no network calls or LLM inference.Retrieve stored results (
x_result_get): saved posts, full text chunks, lossless JSON chunks, and resume cursors without network access.Inspect server status (
x_status): capabilities, recorded provider health, or a tool's input schema.All tools are read-only and use free public API routes first; optional session support; results are paginated, stored locally, and capped in payload size.
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 Research MCP Find public posts discussing MCP and show ten at a time"
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 Research MCP
한국어 · Design and API contract · Verification
A read-only, self-hosted MCP server for public X research. Eight task-oriented tools provide posts, threads, replies, profiles, search, relationships, public collections, trends, and analysis of saved results. It uses the free FxTwitter API first and an optional owner-supplied X session through twscrape where needed. There are no paid API calls or server-side LLM calls.
0.1.0 status: source installation is supported; this is not a claim of PyPI publication. Public post/profile/timeline/thread/reply/trend probes succeeded on 2026-09-16. Free post search returned ambiguous 404s and is reported as unavailable; free user suggestions succeeded through the typeahead route. The session adapter is covered with synthetic tests but has not been tested against an owner's live account. Collections require an explicit public-visibility signal and fail closed when the provider does not supply it. See the capability table before relying on a particular view.
Install and run
Requires Python 3.12+ and uv.
git clone https://github.com/BK927/x-mcp.git
cd x-mcp
uv sync --frozen --no-dev
uv run --frozen --no-dev x-mcp serveNo X login is needed for the public API. Generic local MCP configuration:
{
"mcpServers": {
"x-research": {
"command": "uv",
"args": ["run", "--frozen", "--no-dev", "--directory", "/absolute/path/x-mcp", "x-mcp", "serve"]
}
}
}Use an absolute Windows path such as C:/Users/you/repo/x-mcp when applicable.
The executable is x-mcp; the distribution is bk927-x-mcp. The generic PyPI
name x-mcp is not this project. Repository main can change; check out a reviewed
commit for reproducible source installations.
Related MCP server: X Browser MCP
Tools
Tool | Views / use |
| Public posts or users; posts: latest/top/media |
| post, author thread, replies, quotes, reposters |
| profile, posts, posts with replies, media, articles, followers, following |
| Public list posts/members; community info/posts/members, subject to visibility proof |
| trending; session also supports news/sport/entertainment |
| Saved-post activity, engagement, link domains, hashtags; sample statistics |
| Saved items and lossless text/JSON chunks, without network |
| capabilities, recorded health, or one tool's schema |
Examples: “Read this X thread and cite its posts”; “Find public posts discussing MCP and show ten at a time”; “Compare reaction counts in these saved results, keeping missing metrics separate from zero.”
All tools are read-only. No posting, likes, following changes, DMs, bookmarks, personal home feeds, notifications, account management, or protected content. Search and replies are samples, not a complete X archive. Trend geography is provider-controlled and is not inferred from the client's language.
Optional session: two setup methods
Install the session extra, and keep --extra session in the MCP launch command:
uv sync --frozen --no-dev --extra session
uv run --frozen --no-dev --extra session x-mcp auth import --file /private/path/export.json
uv run --frozen --no-dev --extra session x-mcp serveImport accepts a JSON cookie list, Playwright storage-state JSON, a dictionary
containing auth_token and ct0, or a Netscape cookie file. Only those two X
cookies are retained. Do not paste them into a chat or tool argument.
Alternatively, log in manually in a fresh dedicated browser:
uv sync --frozen --no-dev --extra session --extra browser
uv run --frozen --no-dev --extra session --extra browser playwright install chromium
uv run --frozen --no-dev --extra session --extra browser x-mcp auth loginFinish authentication in the window, then press Enter in the terminal. This does
not import an everyday browser profile, automate passwords, or bypass challenges.
The browser closes after saving the same session file used by auth import.
It is not needed while the server runs. A headless server can mount a session
file prepared on a trusted local machine.
x-mcp auth status validates file presence/format only. x-mcp doctor reports
sanitized configuration and recorded health. x-mcp doctor --live explicitly
queries one public post, profile, and search, using the configured routes.
Session expiry requires reconnecting the account; there is no account rotation.
Compact responses and continuation
Lists default to ten items, at most fifty. detail=compact preserves post ID,
URL, author, timestamp, text and basic reaction counts. Long text is excerpted at
600 characters with a marker. full requests extra fields but still obeys the
12 KiB normalized-payload cap. Both MCP text and structured representations are
provided for compatibility, so clients may consume approximately twice the
payload's tokens; benchmarks report that representation too.
Use a query response's page.next_cursor with the original tool and unchanged
selection arguments. Output-limited leftovers are served before another source
page is fetched. Provider cursors are never mixed. Stored results last one hour
and survive restarts in the same state directory.
For full text: x_result_get(result_id=..., item_id=...). Continue with its
page.next_cursor. Use field=json for lossless chunks of the entire normalized
item. For saved item pages, x_result_get never fetches upstream; its
page.source_cursor, when present, must be passed to the original query tool.
x_analyze processes only posts already saved, not unvisited source pages.
The fixed EN/KO/JA list benchmark meets the 6,000-token tool-list and 50% median payload-reduction targets. Actual savings depend on workload and client; see the methodology and results.
Personal HTTP server
uv run --frozen --no-dev --extra session x-mcp serve --transport httpEndpoints: http://127.0.0.1:8766/mcp, http://127.0.0.1:8766/healthz.
Set MCP_ACCESS_TOKEN to a random secret of at least 32 characters before starting
HTTP, including on loopback. For HTTPS ingress set PUBLIC_BASE_URL=https://x-mcp.example.com
to your exact origin. Clients send Authorization: Bearer ....
Docker is a single-user, single-instance deployment with a persistent state volume. See deployment instructions. Web ChatGPT-specific OAuth, multi-user SaaS, Cloud Run and background collectors are outside v0.1.
Configuration and storage
Environment variable | Default |
| OS user-data directory |
|
|
| 12288; configurable 4096–32768 |
| 3600 seconds; configurable 60–86400 |
| 127.0.0.1, 8766 |
| Empty; mandatory for all HTTP; stdio does not require it |
| Empty; exact HTTPS origin for remote host/origin validation |
State contains public-result snapshots, cached queries, a cursor signing key, health observations and optional session/account files. Queries may themselves be sensitive. Files stay on your machine; protect the whole state directory. FxTwitter receives public lookup IDs/handles/searches, never X cookies. twscrape telemetry is disabled. See privacy and security. X cookies are account credentials, not read-scoped API tokens. The current process can read plaintext session files and its account DB; do not replicate a primary account's cookies across cloud workers. See the credential threat model.
Development
uv sync --frozen --extra session --extra browser
uv run --frozen --extra session --extra browser ruff check src tests scripts
uv run --frozen --extra session --extra browser pytest -q
uv run --frozen --extra session --extra browser python scripts/benchmark_tokens.pyscripts/live_smoke.py makes explicitly opted-in public network calls and stores
only local artifacts. CI uses fixtures, MCP process/HTTP checks and a Docker
smoke test. Browser login and live account access remain operator-run checks.
MIT. Unofficial and unaffiliated with X Corp. Free means no paid data API is called; provider availability, access terms and future pricing can change.
Available Tools
8 toolsx_analyzeARead-onlyIdempotent
Aggregate saved public post results: activity, engagement, link domains, hashtags. No new network fetches or LLM inference; sample statistics only.
Inputs: result_ids (required), mode. Returns: Small shared output schema, rather than eight copies of all X object schemas.
x_collection_getARead-onlyIdempotent
Read public list/community posts or members; community info is also supported. Requires a session and explicit public visibility proof.
Inputs: kind (required), collection (required), view, limit, +2 more. Returns: Small shared output schema, rather than eight copies of all X object schemas.
x_post_getARead-onlyIdempotent
Read a public post by ID/URL, its author thread, replies, quotes, or reposters. Long text can be recovered from its result_id.
Inputs: post (required), sort, view, limit, +2 more. Returns: Small shared output schema, rather than eight copies of all X object schemas.
x_result_getARead-onlyIdempotent
Read saved results without network. Set item_id for full text chunks, or field=json for lossless object chunks. source_cursor resumes the original query tool.
Inputs: result_id (required), field, limit, cursor, +2 more. Returns: Small shared output schema, rather than eight copies of all X object schemas.
x_searchARead-onlyIdempotent
Search public X posts or users. Prefer small pages; results are not exhaustive. Continue with identical query and cursor.
Inputs: query (required), sort, limit, scope, +2 more. Returns: Small shared output schema, rather than eight copies of all X object schemas.
x_statusARead-onlyIdempotent
Inspect capabilities/configuration or recorded provider health. view=schema with tool=NAME returns that tool's input rules. Does not make live probes.
Inputs: tool, view. Returns: Small shared output schema, rather than eight copies of all X object schemas.
x_trends_getBRead-onlyIdempotent
Read provider-context trends. Geography is unknown unless supplied by the source; news/sport/entertainment require a session.
Inputs: limit, cursor, detail, category. Returns: Small shared output schema, rather than eight copies of all X object schemas.
x_user_getARead-onlyIdempotent
Read a public profile or a page of posts, posts with replies, media, articles, followers, or following. Accepts @handle/profile URL.
Inputs: user (required), view, limit, cursor, +1 more. Returns: Small shared output schema, rather than eight copies of all X object schemas.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a clearly distinct data surface: search, post, user, collection, trends, saved-result analysis, raw saved-result retrieval, and server status. x_analyze and x_result_get both operate on saved results, but one computes aggregates while the other returns raw stored chunks, so an agent should not confuse them.
Most tools follow an x_<resource>_get pattern: x_post_get, x_user_get, x_collection_get, x_trends_get, and x_result_get. The exceptions are x_search, x_analyze, and x_status, which break that resource-get convention, but the shared x_ prefix and lowercase snake_case keep the naming mostly predictable.
Eight tools is well-scoped for a read-only X research server. Each tool serves a distinct need, and none feel redundant or excessive for the stated purpose.
The tool surface covers search, post/user/collection/trends reads, saved-result access, and aggregation, which supports the research workflow well. Minor gaps such as no explicit saved-result listing/deletion or batch operations can be worked around by repeated calls or using existing saved-result access.
Maintenance
Related MCP Connectors
Read public Twitter/X data: tweets, profiles, followers, search. No X developer account.
Live X/Twitter data: profiles, tweets, search, followers, lists and trends. 29 read-only tools.
Read-only public X (Twitter) data: profiles, tweets, threads, followers, search. Pay per result.
Search and read public data from X/Twitter, Reddit, YouTube, Instagram, TikTok, Facebook, Threads, Bluesky, Trustpilot, Amazon, Google Maps, news, forums and the web. 90+ read-only tools plus ready-made research playbooks (lead finding, brand monitoring, review mining). Hosted: connect with an API key; 50 free requests per endpoint each month.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables AI agents to search, read user profiles, timelines, media, follow threads, track trends, and manage accounts on X/Twitter via GraphQL, without browser automation or paid API keys.113721 PyPI12MIT
- FlicenseBqualityCmaintenanceEnables browser-based Twitter/X research and account workflows through a signed-in browser, supporting search, timeline/profile reads, saved searches, snapshot exports, and prepared account actions without requiring an X developer API key.25-

@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.1221 npm1MIT- AlicenseNot gradedqualityBmaintenanceProvides read-only access to public X (Twitter) data, including profiles, tweets, timelines, threads, followers, and search, for developers and AI agents.1MIT