Twitter Bridge MCP

Connect Claude.ai to Twitter/X — without paying $100/month for the official API.

Uses bb-browser (open-source browser automation) to control a logged-in Chrome session, wrapped as an MCP server that Claude.ai can talk to.

Claude.ai ──MCP──▶ your-server:8080 ──bb-browser──▶ Chrome (logged in) ──▶ Twitter/X

Cost: ~$5/year (just a domain for Cloudflare Tunnel).

What it can do

| Tool | Method | Status | |------|--------|--------| | twitter_post | Browser automation | ✅ | | twitter_reply | Browser automation | ✅ | | twitter_like | GraphQL API | ✅ | | twitter_retweet | GraphQL API | ✅ | | twitter_quote | Browser automation | ✅ | | twitter_follow | Browser automation | ✅ | | twitter_unfollow | Browser automation | ✅ | | twitter_undo | GraphQL API | ✅ | | twitter_search | Browser DOM parsing | ✅ | | twitter_timeline | Browser DOM parsing | ✅ | | twitter_bookmarks | Browser DOM parsing | ✅ | | twitter_tweets | Browser DOM parsing | ✅ | | twitter_notifications | bb-sites adapter | ✅ | | twitter_user | bb-sites adapter | ✅ | | twitter_view_tweet | Browser DOM parsing | ✅ | | twitter_dm_read | Browser automation | ⚠️ partial | | twitter_screenshot | bb-browser | ✅ | | browser_open | bb-browser | ✅ | | browser_snapshot | bb-browser | ✅ |

DM reading works but Twitter's E2E encryption may limit what's visible via browser automation.

Architecture

The server has three layers:

MCP + OAuth — Claude.ai connects via Streamable HTTP transport with auto-approved OAuth 2.0 (PKCE).
Tool implementations — 19 tools split between browser automation (open page → wait → parse DOM) and GraphQL API calls (for lightweight actions like like/retweet/undo).
bb-browser — Controls Chrome via CDP (Chrome DevTools Protocol), inheriting the logged-in session.

Browser automation was chosen over GraphQL API for most read operations because Twitter's API requires a x-client-transaction-id header generated from webpack internals — the module IDs change on every Twitter deploy, causing random 404s. DOM parsing is slower but never breaks.

Prerequisites

Node.js ≥ 18
Chrome (or Chromium) with remote debugging enabled
bb-browser — Install from GitHub
A Twitter/X account — logged in within the Chrome profile
Cloudflare Tunnel (or any reverse proxy) — to expose your local server with HTTPS

Setup

1. Start Chrome with CDP

# Create a dedicated Chrome profile
mkdir -p ~/chrome-mcp-profile

# Launch Chrome with remote debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=$HOME/chrome-mcp-profile

2. Install & configure

git clone https://github.com/replica882/twitter-bridge-mcp.git
cd twitter-bridge-mcp
npm install

cp .env.example .env
# Edit .env with your values

3. Run

node server.mjs
# Twitter MCP Bridge v0.6.0: http://0.0.0.0:8080/mcp

4. Expose via Cloudflare Tunnel

cloudflared tunnel --url http://localhost:8080

Or set up a named tunnel for a permanent URL.

5. Connect from Claude.ai

In Claude.ai → Settings → Connected Tools → Add Custom Connector:

URL: https://your-tunnel-domain.com/mcp

Claude will auto-discover OAuth endpoints and connect.

Configuration

All config is via environment variables (or .env file):

| Variable | Default | Description | |----------|---------|-------------| | PORT | 8080 | Server port | | CDP_PORT | 9222 | Chrome DevTools Protocol port | | BASE_URL | http://localhost:8080 | Public URL (for OAuth discovery) | | BB_BROWSER_PATH | ~/local/bin/bb-browser | Path to bb-browser binary | | DM_PIN | (empty) | Twitter DM encryption PIN (if set up) | | OAUTH_CLIENT_ID | twitter-mcp-client | OAuth client ID | | OAUTH_CLIENT_SECRET | (auto-generated) | OAuth client secret |

How it works

Why not the official API?

Twitter/X API Basic tier costs $100/month. This project does the same thing for $5/year by automating a real browser session.

Why not just GraphQL?

Twitter's internal GraphQL API requires a x-client-transaction-id header. This ID is generated by a function buried in Twitter's webpack bundles — the module number changes every time Twitter deploys. We use GraphQL only for simple mutations (like, retweet, delete) that don't need this header. Everything else uses DOM parsing.

Tab management

Every browser operation opens a new tab. Without cleanup, Chrome accumulates 40+ tabs and crashes. The server auto-closes excess tabs, keeping a maximum of 10.

DM PIN auto-entry

Twitter requires a PIN every time you open the DM page (E2E encryption). If DM_PIN is set, the server auto-enters it using React-compatible input simulation (native property setter + keyboard events).

Gotchas

Chrome profile encryption — Cookie storage is bound to a profile key. You can't copy a Chrome profile directory to migrate login state. Always use --user-data-dir and log in manually.
React contenteditable — Twitter's compose box is a contenteditable div. Normal DOM manipulation doesn't trigger React state updates. The server uses ClipboardEvent paste for quote tweets and bb-browser's type command for regular posts.
Search occasionally empty — If you search too quickly after page load, DOM might not be populated yet. The server waits 4 seconds, which works reliably.
launchd/systemd and dotenv — If you run the server as a system service, make sure to set WorkingDirectory to the project directory. Without this, dotenv can't find .env, BASE_URL falls back to http://localhost:8080, and OAuth discovery returns localhost URLs — Claude.ai will fail to connect. For macOS launchd, add <key>WorkingDirectory</key><string>/path/to/twitter-bridge-mcp</string> to your plist. For systemd, add WorkingDirectory=/path/to/twitter-bridge-mcp to your unit file.
Server restart loses OAuth tokens — OAuth tokens are stored in memory. Every server restart requires reconnecting from Claude.ai (Settings → Connected Tools → reconnect Twitter Bridge).

Credits

bb-browser — the browser automation engine that makes this possible
MCP SDK — Model Context Protocol server framework
Cloudflare Tunnel — free HTTPS tunneling

License

MIT

MCP Servers