Twitter Mcp

Twitter/X MCP Server

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

[](https://www.python.org/downloads/) [](LICENSE) [](https://modelcontextprotocol.io) [](#tools) [](https://github.com/Miles0sage/twitter-mcp)

---

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

| Category | Tool | Description | Auth Required | |----------|------|-------------|:---:| | Read | twitter_search | Search tweets by keyword or hashtag | No | | | twitter_feed | Read your home timeline | Yes | | | twitter_bookmarks | Read your saved bookmarks | Yes | | | twitter_user | Get a user's profile info | No | | | twitter_user_tweets | Get tweets from a specific user | No | | | twitter_trending | Get trending topics | No | | | twitter_notifications | Read your notifications | Yes | | Write | twitter_post | Post a new tweet | Yes | | | twitter_reply | Reply to a tweet | Yes | | | twitter_like | Like a tweet | Yes | | | twitter_retweet | Retweet a tweet | Yes |

> 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

| Feature | Twitter MCP | Twitter API (Basic) | Twitter API (Pro) | Apify Scrapers | |---------|:-:|:-:|:-:|:-:| | Cost | Free | $100/mo | $5,000/mo | Per-run fees | | Auth | Browser login | OAuth + API key | OAuth + API key | API key | | Post tweets | Yes | Yes | Yes | No | | Read feed | Yes | Limited | Yes | Yes | | Bookmarks | Yes | No | Yes | No | | Search | Yes | Limited | Yes | Yes | | Rate limits | Browser-level | Strict | Strict | Per-plan | | MCP native | Yes | No | No | No | | Setup time | 2 min | 30+ min | Application | 10 min |

---

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Miles0sage
• Source: Miles0sage/twitter-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.