Xee-mcp
Xee-mcp is a read-only MCP server for searching X posts and reading a user's recent timeline.
search(query, limit=20): search X posts by keyword, supporting X search syntax likefrom:,to:,since:,until:, exact phrases, exclusions, andOR.user_tweets(handle, limit=20): read recent posts from an X user, passing the handle without@.Results include post text, author, timestamp, URL, and engagement stats.
Read-only only: no posting, DMs, likes, retweets, or analytics.
In v0.1.0, both tools are temporarily degraded due to an upstream twikit parsing issue and may return an
upstreamerror until fixed.
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., "@Xee-mcp search for posts about MCP protocols this week"
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.
Xee-mcp — MCP server for X (Twitter): search + read, no paid API
What is Xee-mcp? It's a Model Context Protocol server that gives Claude, ChatGPT, and other AI assistants two read-only tools for X (Twitter): search posts and read a user's timeline. It uses cookie-based auth via twikit — no X API keys, no pay-per-use fees.
Naming: X + See = Xee (pronounced "ex-ee"). The name encodes the scope — Xee-mcp is for seeing X, not posting to it. Posting is intentionally out-of-scope for v0.x.
Status (v0.1.0)
xee-mcp init (cookie setup) works. search and user_tweets are temporarily degraded — they return a failure result with "class": "upstream" because twikit (the underlying scrape library) can't parse X's current webpack chunk format to build the X-Client-Transaction-Id header. This is not a cookie problem — your auth is fine.
This is upstream's repo to fix; we don't fork or maintain a patched scraper. When twikit ships a parser fix, bump the dep and these tools resume working with no code change on your side. See docs/upstream-issues.md for the technical details.
Why ship now anyway: the setup UX (xee-mcp init) is the value users feel first. Shipping that lets people install, configure, and be ready — so the day upstream lands a fix, the tools just start working.
Related MCP server: agent-twitter-client-mcp
Why Xee-mcp
Several MCP servers for X already exist. Most require the paid X API — pay-per-use since Feb 2026, ~$0.005 per read. For solo developers and OSS authors who just want to let Claude search what's being said about their work, that's wrong shape.
Xee-mcp solves one job: read X with zero API cost. Cookie auth via twikit, two tools, one MCP server. That's it.
Xee-mcp | |||||
Auth | Cookie (twikit) | Browser session (api-anything) | Cookie (twikit) | OAuth 2.0 | OAuth 1.0a |
API cost | $0 | $0 | $0 | Pay-per-use | Pay-per-use |
Scope | Read + search only, no write code | Read + write ( | Read + search + post + DMs | Full | Full |
Tools count | 2 (focused) | 27 | ~10+ | ~10+ | ~10+ |
Runtime | Python 3.11+ | Node 22.13+ | Python | Python | Python |
Goal | Minimal, solo-OSS friendly | Your whole account for agents | Power user | Production | Production |
Need reads that work today? While twikit is broken (see Status), crossbar is the closest no-API option: crossbar setup --read-only registers no write tools. Its Claude Code plugin install does include them.
If you want posting, DMs, or production-grade reliability — use one of the others. If you want the smallest thing that lets Claude see X for you, use Xee-mcp.
Tools
search(query, limit=20)
Search X posts by keyword. Returns text, author, timestamp, URL, and engagement stats.
user_tweets(handle, limit=20)
Read a user's recent posts. Returns the same fields.
That's the v0.1 surface. Two tools. Read-only. No surprises.
When a tool can't answer
It returns isError: true with a JSON body your assistant can act on:
{ "ok": false, "class": "auth", "reason": "…", "next": "No usable cookie file. Run: xee-mcp init, …" }
| Means | What to do |
| Cookie file missing, expired or rejected |
|
| The scrape library broke against X; cookies are fine | Wait for the fix (see Status). Don't re-auth |
| Empty query, | Fix the arguments |
| X is rate-limiting this session | Wait ~15 min. Don't retry in a loop |
| Anything else | Retry once, then rerun with |
Install
git clone https://github.com/Aiyo28/Xee-mcp.git
cd Xee-mcp
uv syncPyPI publish follows the first wave of feedback (pip install xee-mcp).
Quickstart
Log in to x.com in Chrome (or Brave / Arc / Firefox / Safari / Edge — any one).
One-shot cookie setup. Reads your existing browser session — no extension, no DevTools paste, no password:
uv run xee-mcp init export XEE_MCP_COOKIES=~/.config/xee-mcp/cookies.jsonOn macOS Chrome / Brave / Edge you'll see one Keychain prompt — approve it. For other browsers use
--browser brave|arc|firefox|safari|edge. Other setup paths (advanced / headless) are in docs/cookies.md.Wire into your client. Print the config with absolute paths filled in. GUI apps like Claude Desktop and Cursor don't load your shell
PATH, so a bareuvorxee-mcpoften fails to start there:uv run xee-mcp config # Claude Desktop, Claude Code and Cursor uv run xee-mcp config --client claude-code # one client: claude-desktop | claude-code | cursorPaste the JSON into
claude_desktop_config.json(or~/.cursor/mcp.json), or run the printedclaude mcp addline. It prints only; no file is written. Prefer to write it by hand? See examples/.Ask Claude:
"Search X for posts about MCP servers from the last week." "Show me the last 10 posts from @simonw."
Limitations
Single account. v0.1 uses one cookie file. If X bot-detects, you wait it out or rotate. Multi-account pool is roadmapped (see twscrape swap path in ROADMAP.md).
Read-only. No post, no DMs, no like/retweet. Intentional — see naming.
No analytics dashboard. This is a primitive, not a product. Compose with other MCP tools.
Cookie auth is brittle by design. X may rotate session formats. Pin issues here.
Roadmap
See ROADMAP.md. v0.2 likely adds replies + bookmarks (still read). Posting stays separate (different threat model, different repo).
Support the project
Xee-mcp is MIT, ad-free, and will never have paid tiers. If it saves you time or money, you can throw a coffee:
paypal.me/aiyo28 — keeps everything ad-free, no paid tiers, ever.
Or just star the repo and tell someone. That works too.
Related projects
Yzel — MCP connectors for CIS business tools (1C, Wildberries, Ozon, Bitrix24, AmoCRM, МойСклад, Telegram, iiko). Sibling OSS project, different scope (CIS-first business APIs).
License
MIT. See LICENSE.
Available Tools
2 toolssearchA
Search X (Twitter) posts by keyword. Read-only.
Supports X search syntax: from:handle, to:handle, since:YYYY-MM-DD, until:YYYY-MM-DD,
"exact phrase", -exclude, OR. Returns latest matches.
Inputs: query (required), limit. Returns: result
user_tweetsA
Read recent posts from an X (Twitter) user. Read-only.
Pass the handle without @. Example: handle="simonw" → fetches simonw's recent posts.
Inputs: handle (required), limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one searches by keyword across posts, the other retrieves posts from a specific user. There is no overlap or ambiguity.
Both tool names are lowercase and concise, but 'search' is a verb while 'user_tweets' is a noun phrase. The style is mostly consistent, with a minor deviation.
With only 2 tools for the X platform, the scope is quite limited. While a small set can be appropriate for a focused server, this feels insufficient for comprehensive X interaction.
The server lacks many fundamental operations for social media data, such as posting, user profiles, trending topics, or thread fetching. The tool surface is severely incomplete.
Maintenance
Related MCP Connectors
X (formerly Twitter) posts, profiles, and search for AI agents. Free key, self-minted, no signup.
Read public Twitter/X data: tweets, profiles, followers, search. No X developer account.
Read public X posts and full X Articles as clean Markdown. Free, no X API key.
Search X (Twitter) posts and read profiles, followers, trends and X Articles. OAuth sign-in.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceConnects AI assistants to Twitter/X using cookie-based authentication to read timelines, search tweets, and perform actions like posting and liking. It leverages Twitter's internal GraphQL API to provide full functionality without requiring a developer account.19 npm-
- AlicenseBqualityDmaintenanceEnables AI models to interact with Twitter, including posting tweets, searching, following users, and chatting with Grok, using cookie or credential authentication.141MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to fully automate X/Twitter interactions including searching, posting, engaging, and managing multiple accounts without paid API keys.MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to interact with Twitter/X using session cookies. Supports posting, searching, managing tweets, viewing trends, and user profiles.-