xbird — Twitter/X for AI Agents

MCP server that gives AI agents (Claude Code, Cursor, Windsurf) 35 Twitter/X tools — reading, searching, posting, engagement, media upload — with per-call x402 micropayments on Base.

No API keys, no developer account.

Quick Start

Two runtime options — pick one:

Option A: Bun (recommended)

Auto-detects your Twitter session from Chrome, Firefox, Edge, or Safari. Zero manual setup.

Claude Code:

claude mcp add xbird -- bunx @checkra1n/xbird

Cursor / Windsurf — add to .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "xbird": {
      "command": "bunx",
      "args": ["@checkra1n/xbird"]
    }
  }
}

Requires Bun (curl -fsSL https://bun.sh/install | bash).

Option B: Node.js (npx)

Works with Node.js >= 18. Requires one-time login to paste cookies.

Claude Code:

claude mcp add xbird -- npx @checkra1n/xbird

Cursor / Windsurf — add to .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "xbird": {
      "command": "npx",
      "args": ["-y", "@checkra1n/xbird"]
    }
  }
}

Then run the login command once:

npx @checkra1n/xbird login

Copy auth_token and ct0 from x.com → DevTools (F12) → Application → Cookies → https://x.com.

Comparison

| | Bun (bunx) | Node.js (npx) | |--|---|---| | Browser cookies | Auto-detected | Manual login required | | Setup | Install Bun, done | One-time login command | | Runtime | Bun | Node.js >= 18 | | Startup | Faster | Slower (npm registry check) |

Alternative auth methods

All methods work with both runtimes:

| Method | How | |--------|-----| | Login command | npx @checkra1n/xbird login — prompts for cookies, saves to config | | Env vars | claude mcp add xbird -e XBIRD_AUTH_TOKEN=xxx -e XBIRD_CT0=yyy -- bunx @checkra1n/xbird | | Config file | Add authToken/ct0 to ~/.config/xbird/config.json |

How It Works

AI Agent (Claude Code / Cursor / Windsurf)
  │  MCP stdio
bunx/npx @checkra1n/xbird (local MCP server)
  ├── Twitter API calls → DIRECT to api.x.com (your IP)
  └── x402 payment → xbird server (only payment, no credentials)

The MCP server runs entirely on your machine. Twitter API calls go directly from your residential IP — credentials never leave your computer. Only x402 micropayments touch the remote server.

CLI

# Login (save credentials locally)
npx @checkra1n/xbird login

Tools (35)

Read — $0.001/call

| Tool | Description | |------|-------------| | get_tweet | Get a tweet by ID | | get_thread | Get a tweet thread (conversation chain) | | get_article | Get full article/long-form post content | | get_replies | Get replies to a tweet | | get_user | Get user profile by handle | | get_user_about | Get detailed user info (bio, location, joined date) | | get_current_user | Get the authenticated user's profile | | get_home_timeline | Get home timeline | | get_news | Get trending news/topics | | get_lists | Get owned Twitter lists | | get_list_timeline | Get tweets from a list |

Search — $0.005/call

| Tool | Description | |------|-------------| | search_tweets | Search for tweets by query | | get_mentions | Get mentions for a user |

Bulk — $0.01/call

| Tool | Description | |------|-------------| | get_user_tweets | Get tweets posted by a user | | get_followers | Get a user's followers | | get_following | Get users that a user follows | | get_likes | Get tweets liked by a user | | get_bookmarks | Get bookmarked tweets | | get_list_memberships | Get lists the user is a member of |

Write — $0.01/call

| Tool | Description | |------|-------------| | post_tweet | Post a new tweet | | reply_to_tweet | Reply to a tweet | | post_thread | Post a thread (multiple tweets) | | like_tweet / unlike_tweet | Like or unlike a tweet | | retweet / unretweet | Retweet or undo | | bookmark_tweet / unbookmark_tweet | Bookmark or remove | | follow_user / unfollow_user | Follow or unfollow |

Profile — $0.01/call

| Tool | Description | |------|-------------| | update_profile | Update bio/description | | update_profile_image | Update avatar | | update_profile_banner | Update banner image | | remove_profile_banner | Remove banner |

Media — $0.05/call

| Tool | Description | |------|-------------| | upload_media | Upload image/video, returns mediaId for use in tweets |

Payments

Every tool call makes a micropayment via the x402 protocol on Base (L2). Prices range from $0.001 (reading a tweet) to $0.05 (uploading media). A typical 9-call agent session costs ~$0.08.

A wallet is auto-generated at ~/.config/xbird/wallet.json on first run. Fund it with USDC on Base.

REST API

For developers and AI agents that need direct HTTP access:

# 1. Generate stateless token (encrypts credentials locally)
npx @checkra1n/xbird login

# 2. Fund wallet with USDC on Base (~$0.01 for hundreds of calls)
#    Address shown in login output

# 3. Use the token in requests
curl https://xbirdapi.up.railway.app/api/search?q=AI+agents \
  -H "X-Encryption-Key: <your-xbird-token>"

The server is fully stateless — no database, no stored credentials. Your token contains encrypted credentials, decrypted per-request then discarded.

Distribution

| Platform | Install | |----------|---------| | npm (Bun) | bunx @checkra1n/xbird | | npm (Node.js) | npx @checkra1n/xbird | | Claude Code | claude mcp add xbird -- bunx @checkra1n/xbird | | Cursor / Windsurf | Add to .cursor/mcp.json (see above) | | Claude Code Plugin | /plugin install checkra1neth/xbird | | skills.sh | npx skills add checkra1neth/xbird |

License

MIT