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
Log in to Twitter/X in this Chrome window.
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-dirand log in manually. - React contenteditable — Twitter's compose box is a
contenteditablediv. Normal DOM manipulation doesn't trigger React state updates. The server usesClipboardEvent pastefor quote tweets and bb-browser'stypecommand 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
WorkingDirectoryto the project directory. Without this, dotenv can't find.env,BASE_URLfalls back tohttp://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, addWorkingDirectory=/path/to/twitter-bridge-mcpto 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