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_mentions	Browser DOM parsing	✅
twitter_my_replies	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.

What's new in v0.6.1

• twitter_view_tweet now includes replies — Pass include_replies: true (default) to fetch up to 20 replies from the tweet's thread. Uses cellInnerDiv container traversal with auto-scrolling.
• New: twitter_mentions — Fetches tweets that mention/reply to you from the Mentions tab.
• New: twitter_my_replies — Fetches your own replies to other tweets. Requires screen_name parameter.
• Token persistence — OAuth tokens are now saved to .tokens.json and survive server restarts. No more re-authenticating after every reboot.
• Tab switching fix — Fixed a bug where bb-browser open creates a new tab without switching to it, causing all subsequent operations to run on the wrong page. Affects view_tweet, openAndParseTweets (used by timeline, search, bookmarks, tweets, mentions, my_replies).
• Smart page loading — view_tweet now polls for the main tweet article to appear (up to 15s) instead of using a fixed sleep, improving reliability on slow connections.

Architecture

The server has three layers:

1. MCP + OAuth — Claude.ai connects via Streamable HTTP transport with auto-approved OAuth 2.0 (PKCE).
2. Tool implementations — 19 tools split between browser automation (open page → wait → parse DOM) and GraphQL API calls (for lightweight actions like like/retweet/undo).
3. 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.1: 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