x-readonly MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
x-readonly MCP Server
A resilient, strictly read-only X (Twitter) Model Context Protocol (MCP) server.
It combines passwordless public reading (via a FxTwitter v2 API -> X oEmbed fallback chain that requires zero cookies to read tweets, Note Tweets, full X Articles, and public user timelines) with authenticated GraphQL reading (featuring live x-client-transaction-id transaction signing and self-healing GraphQL queryId extraction from X's web bundle for search, followers, lists, and trends).
Key Features
Dual-Path Resilience (Works Without Login)
get_tweetandget_user_tweetssupportsource="public"(orsource="auto"for automatic fallback).The public path (
FxTwitter API -> X Official oEmbed) never touches your cookies and preserves long-form Note Tweets (>500 chars) as well as multi-thousand-word X Articles (article.content.blocks).
Self-Healing GraphQL Endpoints & Live Transaction Signing
Solves the common
401 / 403 / 404breakage in third-party scrapers caused by stale bearer tokens or missingx-client-transaction-idheaders.When X rotates GraphQL
queryIds, the server automatically extracts the latestqueryId,featureSwitches, andfieldTogglesfromx.com's livemain.*.jsbundle and updatesgraphql_endpoints.json.
Strictly Read-Only & Rate-Limit Safe
Zero Write Operations: Contains no endpoints for posting, liking, retweeting, following, or DMing — eliminating account action risk.
Built-in Throttling & Short Caching: Enforces a
1.5sglobal minimum interval between requests +60sin-memory TTL cache + per-call item caps.Hot-Reloaded Credentials: Re-reads
.envor environment variables on each call so updating cookies never requires restarting the MCP server.
Related MCP server: X Research MCP
Available Tools (13)
Tool | Cookie Required? | Description |
| No ( | Read full tweet text, metrics, Note Tweets, and X Articles by tweet ID (auto-falls back to public path if primary fails) |
| No ( | Read a user's recent timeline and pagination cursor ( |
| Optional | Separately checks authenticated GraphQL endpoints and public single-post reading ( |
| Yes | Search tweets by query (supports |
| Yes | Search X user accounts by keyword |
| Yes | Get user profile details (bio, followers, following, verification status, etc.) |
| Yes | Get the profile of the account owning the configured cookie (requires |
| Yes | Get recent tweets mentioning ( |
| Yes | List followers of a given user |
| Yes | List accounts followed by a given user |
| Yes | List public X Lists created by a user |
| Yes | Read the latest tweets from a specific List ID |
| Yes | Get trending topics by WOEID ( |
Quick Start
1. Install Dependencies
Python 3.10+ in a virtual environment is recommended:
git clone https://github.com/junjiemi23-ship-it/x-readonly-mcp.git
cd x-readonly-mcp
python -m venv .venv
# Windows:
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux:
.venv/bin/pip install -r requirements.txt2. (Optional) Configure Cookies for Search & GraphQL
If you only need to read shared X links or public user timelines, you can skip this step and call get_tweet(..., source="public") or get_user_tweets(..., source="public").
To enable search_tweets and other authenticated tools, configure .env:
Option A: Interactive Hidden Input (Recommended)
python set_cookie.pyOption B: Copy
.env.exampleto.envGrabauth_token,ct0(required), andtwid(optional) from an authenticatedhttps://x.combrowser session (F12 -> Application -> Cookies) and set:TWITTER_COOKIES='auth_token=xxx; ct0=yyy; twid=u%3D123456'
3. Wire into Your MCP Client (Claude Desktop / Cursor / Codex / Antigravity)
Add to your MCP configuration file:
{
"mcpServers": {
"x-readonly": {
"command": "/path/to/x-readonly-mcp/.venv/Scripts/python.exe",
"args": ["-u", "/path/to/x-readonly-mcp/server.py"]
}
}
}(On macOS / Linux, use /path/to/x-readonly-mcp/.venv/bin/python)
Self-Test & Troubleshooting
# Test passwordless public fallback chain directly
python x_public_fallback.py 2088993353111159216
# Full MCP stdio client self-test (requires cookie for search/profile checks)
python selftest.pyOperational Notes
transaction_signerfailure does NOT automatically mean expired cookies: When logged out or challenged, X's homepage servesentry-client-logged-outbundles without theondemand.smapping. Even ifhealth_check.api_okisfalse, do not skip public reading —source="public"works independently.Cursor Isolation: Public timeline pagination returns cursors prefixed with
fxtwitter:. Pass them back as-is; never mix authenticated GraphQL cursors with public timeline cursors.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Read public Twitter/X data: tweets, profiles, followers, search. No X developer account.
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/Twitter reads, search, monitors and posting. Pay-per-call in USDC — no signup, no API keys.
Related MCP Servers
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

TweetAPI MCPofficial
AlicenseAqualityBmaintenanceEnables AI agents to read public Twitter data—including search, profiles, followers, timelines, lists, communities, and Spaces—and look up API documentation. It supports hosted OAuth or local stdio connections and exposes only read-only tools.522MIT