# Twitter Bridge MCP

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

Uses [bb-browser](https://github.com/epiral/bb-browser/releases/tag/bb-browser-v0.10.0) (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](https://github.com/epiral/bb-browser/releases/tag/bb-browser-v0.10.0)
- **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

```bash
# 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

```bash
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

```bash
node server.mjs
# Twitter MCP Bridge v0.6.1: http://0.0.0.0:8080/mcp
```

### 4. Expose via Cloudflare Tunnel

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

Or set up a [named tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) 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](https://github.com/epiral/bb-browser/releases/tag/bb-browser-v0.10.0) — the browser automation engine that makes this possible
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) — Model Context Protocol server framework
- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — free HTTPS tunneling

## License

MIT