Twitter/X MCP Server

Read, search, and post on Twitter/X from any AI agent. No API key needed – uses persistent browser sessions.

---

Why This Exists

Twitter’s API costs $100+/month and rate-limits everything. This MCP server uses Playwright browser automation with a persistent Chrome profile instead – zero API fees, no rate limit headaches. Your AI agent gets full Twitter access through the Model Context Protocol.

Works with Claude Code, Cursor, Windsurf, or any MCP-compatible client.

---

Tools

No API key needed. Read-only tools work without authentication. Write tools require a one-time browser login (cookies persist automatically).

---

Quick Start

git clone https://github.com/Miles0sage/twitter-mcp.git
cd twitter-mcp
pip install -r requirements.txt
playwright install chromium

Add to your MCP config (~/.mcp.json or client settings):

{
  "mcpServers": {
    "twitter": {
      "command": "python3",
      "args": ["server.py"],
      "cwd": "/path/to/twitter-mcp"
    }
  }
}

---

Authentication

This server uses a persistent Chrome profile stored at ~/.twitter-mcp/chrome-profile/. Log in once and your session persists across restarts.

First-time setup

# Opens a real browser -- log in to Twitter/X manually
python3 -c "from browser_session import login; login()"

Once logged in, cookies are saved to the Chrome profile. All future MCP calls reuse the session automatically.

Headless vs non-headless

Twitter blocks headless browsers. The server runs Chromium with DISPLAY=:99 (Xvfb) by default for server environments. On desktop, it uses your normal display.

# Server/VPS setup
export DISPLAY=:99
Xvfb :99 -screen 0 1920x1080x24 &

Keepalive

A keepalive script prevents session expiry by loading Twitter periodically:

# Add to crontab (every 30 min)
*/30 * * * * DISPLAY=:99 python3 /path/to/twitter-mcp/twitter_keepalive.py

---

Usage Examples

"Search Twitter for AI agent news"
  -> Latest tweets matching query, with engagement stats

"Read my feed"
  -> Your home timeline, newest first

"Show my bookmarks"
  -> Your saved/bookmarked tweets

"Post: Just shipped a new MCP server!"
  -> Tweet posted, returns URL

"What's trending?"
  -> Top trending topics with tweet counts

"Get @elonmusk's recent tweets"
  -> Latest tweets from the user

---

Architecture

LLM / MCP Client
       |
  MCP Protocol (stdio)
       |
  server.py ── registers 11 tools
       |
  +----+----+--------+
  |         |        |
tools_   tools_   tools_
read.py  feed.py  write.py
  |         |        |
  +----+----+--------+
       |
  browser_session.py
  (persistent Chromium via Playwright)
       |
  ~/.twitter-mcp/chrome-profile/
  (cookies + session state)

---

Project Structure

server.py               # MCP server, tool registration
tools_read.py           # Search, user profile, user tweets, trending
tools_feed.py           # Feed, bookmarks, notifications
tools_write.py          # Post, reply, like, retweet
browser_session.py      # Playwright session management, persistent Chrome profile
twitter_keepalive.py    # Session keepalive cron script
api_server.py           # Optional REST API wrapper

---

Comparison

---

License

MIT