Skip to main content
Glama
Xee-mcp
by Aiyo28

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.

MIT License Python 3.11+ MCP Compatible

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

crossbar

mcp-twikit

official xmcp

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 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, …" }

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

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:

    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.

  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:

    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/.

  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 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.


  • 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 tools
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

    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

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI models to interact with Twitter, including posting tweets, searching, following users, and chatting with Grok, using cookie or credential authentication.
      14
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to fully automate X/Twitter interactions including searching, posting, engaging, and managing multiple accounts without paid API keys.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to interact with Twitter/X using session cookies. Supports posting, searching, managing tweets, viewing trends, and user profiles.
      -