twikit-x-mcp

An MCP (Model Context Protocol) server that lets an AI assistant — Claude Desktop, Claude Code, Cursor, or any MCP client — read and act on Twitter / X through a single authenticated session. No official X API key required.

Built on twikit

All the real work — the actual Twitter/X client — is twikit by d60. Full credit and rights to the original library belong to its author. This project is only a thin MCP wrapper around it. ⭐ Please star the original repo.

It exposes twikit's capabilities as clean, model-friendly MCP tools.

⚠️ This repo bundles a lightly patched copy of twikit (under twikit/, MIT — see licenses/twikit-LICENSE.txt), because the published twikit is currently broken on X (the Couldn't get KEY_BYTE indices login bug). The patch only fixes login. When upstream ships a fix, the bundled copy can be dropped in favour of the PyPI twikit package.

Full reference: Documentation · Setup: INSTALL.md · Changelog: CHANGELOG.md · Versioning & releases: docs/RELEASES.md

Related MCP server: X(Twitter) V2 MCP Server

Features

• 27 tools covering users, tweets (read + write), timelines, trends and DMs.

• No X API key — authenticates as a normal account via cookies or login.

• Built-in rate limiting, on by default, to help avoid suspension (configurable).

• One-line run with uvx (no manual install), or pip.

Paginating tools return { "items": [...], "count": N, "next_cursor": "..." }; pass next_cursor back in to page.

Tool annotations

Per the MCP annotations spec — side effects at a glance. Write tools act on your real account.

Install

Install and run with uvx:

uvx twikit-x-mcp

Note: the Python import module is twikit_x_mcp (underscore), per Python convention. The distribution is self-contained — twikit is bundled in, so there are no external Git dependencies to resolve.

Connect your MCP client

Per-client, copy-paste setup for Claude Code, Claude Desktop, Cursor, Windsurf, VS Code and more is in INSTALL.md.

Using a client that isn't documented there? Point its AI at llms-install.md — a machine-readable install spec an agent can follow to wire this server into any MCP client.

Authenticate

X's automated login regularly trips a Cloudflare / "verify you're human" challenge, so the reliable way to authenticate is to copy two cookies from a browser where you're already logged in to x.com: auth_token and ct0.

1. Grab the cookies

1. Log in to https://x.com in your browser.

2. Open DevTools → Application (Chrome/Edge) or Storage (Firefox) → Cookies → https://x.com.

3. Copy the Value of auth_token and of ct0.

2. Set them as environment variables

🔐 Treat these like a password — they grant access to your account. Don't commit them anywhere. They rotate when you log out of that browser session, so refresh them if requests start failing.

See INSTALL.md for exactly where these go in each client's config.

Rate limiting

To reduce the risk of rate-limit errors or account suspension, the server throttles tool calls by default (token bucket, 30 calls/minute).

Call the rate_limit_status tool to see the active configuration.

Run manually

python -m twikit_x_mcp      # or:  twikit-x-mcp

You normally won't run it by hand — your MCP client launches it. See INSTALL.md for client setup.

Troubleshooting

Responsible use

Automating X may violate its Terms of Service and can get accounts rate-limited or suspended. Use a purpose-made account, keep volume low, and respect twikit's rate-limit notes. Don't use this for spam, harassment, or mass automation.

Contributing

Contributions welcome! This project uses Conventional Commits for commits, PR titles and issue titles — see CONTRIBUTING.md.

Security & conduct: SECURITY.md · Code of Conduct

Credits

• twikit by d60 — the underlying X client that does all the heavy lifting (MIT). A patched copy is bundled here under twikit/; its license is preserved at licenses/twikit-LICENSE.txt. ⭐ Please star the original repo.

• This project (twikit-x-mcp) is MIT-licensed. See LICENSE.

Disclaimer

This is an unofficial project. It is not affiliated with, authorized, maintained, sponsored, or endorsed by X Corp. (Twitter).

It authenticates as your own account using session cookies and drives X through twikit — an unofficial client — so a tool can break when X changes its site. Automating X may violate its Terms of Service and can get accounts rate-limited or suspended.

You are responsible for using this software in compliance with X's Terms of Service and applicable law. Use a purpose-made account, keep volume low, and don't use it for spam, harassment, or mass automation. All product names, logos, and brands are property of their respective owners.