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.
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.
xee-mcp init (cookie setup) works. search and user_tweets are temporarily degraded — they return a clear "upstream parser broken" error 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
Six 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) | Cookie (twikit) | OAuth 2.0 | OAuth 1.0a |
API cost | $0 | $0 | Pay-per-use | Pay-per-use |
Scope | Read + search only | Read + search + post + DMs | Full | Full |
Tools count | 2 (focused) | ~10+ | ~10+ | ~10+ |
Goal | Minimal, solo-OSS friendly | Power user | Production | Production |
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.
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.
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).
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 Claude Desktop / Claude Code. Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"xee-mcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/Xee-mcp", "xee-mcp"],
"env": { "XEE_MCP_COOKIES": "/path/to/cookies.json" }
}
}
}Ask Claude:
"Search X for posts about MCP servers from the last week." "Show me the last 10 posts from @simonw."
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.
See ROADMAP.md. v0.2 likely adds replies + bookmarks (still read). Posting stays separate (different threat model, different repo).
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).
MIT. See LICENSE.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature and states it returns latest matches. However, no annotations are provided, so the description carries full burden; it lacks details on rate limits, pagination, or what 'latest' means precisely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first defines purpose, second lists syntax. Front-loaded and efficient, though the syntax list could be slightly streamlined.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, return structure may be covered. But description lacks comparison to sibling tool and omits pagination info. Adequate for a simple search tool but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds value by explaining the query syntax with examples. However, it does not elaborate on the 'limit' parameter beyond the schema's default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it searches X (Twitter) posts by keyword, and specifies it's read-only. Differentiates from sibling tool 'user_tweets' by implying keyword-based search rather than user-specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides detailed X search syntax (from:, since:, etc.) but does not explicitly state when to use this tool vs. the sibling 'user_tweets'. No 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read recent posts from an X (Twitter) user. Read-only.
Pass the handle without @. Example: handle="simonw" → fetches simonw's recent posts.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description states 'Read-only' which is good, but lacks disclosure of rate limits, pagination, or definition of 'recent'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 params and no annotations, description covers handle well but omits output format details, pagination, and explicit guidance on sibling tool distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds crucial meaning for the handle parameter (format without @, example). However, the limit parameter is not explained beyond schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Read recent posts from an X (Twitter) user' with a specific verb and resource. Distinguishes from sibling 'search' tool by specifying user scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides example and mentions read-only behavior, but does not explicitly contrast with sibling 'search' tool or indicate when to use one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0searchuser_tweetsScored 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.
X (formerly Twitter) posts, profiles, and search for AI agents. Free key, self-minted, no signup.
Twitter (X) API alternative for AI agents: tweet search, profiles, followers. $0.0002 per result.
X/Twitter reads, search, monitors and posting. Pay-per-call in USDC — no signup, no API keys.
X / Twitter public post, comment, reply, user, and search tools.
