Xee-mcp
by Aiyo28
README.md
<p align="center">
<img src="https://raw.githubusercontent.com/Aiyo28/Xee-mcp/master/docs/assets/banner.jpg" alt="Xee: the view through binoculars onto a feed of X posts" width="100%">
</p>
# Xee-mcp — MCP server for X (Twitter): search + read, no paid API
> **What is Xee-mcp?** It's a [Model Context Protocol](https://modelcontextprotocol.io) 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](https://github.com/d60/twikit) — no X API keys, no pay-per-use fees.
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
**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](https://github.com/d60/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](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.
---
## Why Xee-mcp
Several MCP servers for X already exist. Most require the [paid X API](https://docs.x.com/x-api/getting-started/about-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 | [crossbar](https://github.com/prantikmedhi/crossbar) | [mcp-twikit](https://github.com/adhikasp/mcp-twikit) | [official xmcp](https://github.com/xdevplatform/xmcp) | [Infatoshi/x-mcp](https://github.com/Infatoshi/x-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-only` flag) | 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](https://github.com/prantikmedhi/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:
```json
{ "ok": false, "class": "auth", "reason": "…", "next": "No usable cookie file. Run: xee-mcp init, …" }
```
| `class` | Means | What to do |
|---|---|---|
| `auth` | Cookie file missing, expired or rejected | `xee-mcp init --force` |
| `upstream` | The scrape library broke against X; cookies are fine | Wait for the fix (see Status). Don't re-auth |
| `input` | Empty query, `limit < 1`, or not a valid handle | Fix the arguments |
| `blocked` | X is rate-limiting this session | Wait ~15 min. Don't retry in a loop |
| `error` | Anything else | Retry once, then rerun with `XEE_MCP_DEBUG=1` and open an issue |
---
## Install
```bash
git clone https://github.com/Aiyo28/Xee-mcp.git
cd Xee-mcp
uv sync
```
PyPI publish follows the first wave of feedback (`pip install xee-mcp`).
---
## Quickstart
1. **Log in to x.com in Chrome** (or Brave / Arc / Firefox / Safari / Edge — any one).
2. **One-shot cookie setup.** Reads your existing browser session — no extension, no DevTools paste, no password:
```bash
uv run xee-mcp init
export XEE_MCP_COOKIES=~/.config/xee-mcp/cookies.json
```
On 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](docs/cookies.md).
3. **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 bare `uv` or `xee-mcp` often fails to start there:
```bash
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 | cursor
```
Paste the JSON into `claude_desktop_config.json` (or `~/.cursor/mcp.json`), or run the printed `claude mcp add` line. It prints only; no file is written. Prefer to write it by hand? See [examples/](examples/).
4. **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](https://github.com/vladkens/twscrape) swap path in [ROADMAP.md](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](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](https://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](https://github.com/Aiyo28/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](LICENSE).
TDQS
A3.7/5.0
Scored across 2 tools
Disambiguation5/5
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.
Naming Consistency4/5
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.
Tool Count3/5
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.
Completeness2/5
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
ActivityNo data
ResponsivenessOutdated data