@checkra1n/xbird

xbird — Twitter/X for AI Agents

MCP server that gives AI agents 247 Twitter/X tools — reading, searching, posting, engagement, media, communities, Grok, Birdwatch, and more — with per-call x402 micropayments on Base.

No official API keys. No developer account.

Quick Start

Bun (recommended) — auto-detect browser cookies

claude mcp add xbird -- bunx @checkra1n/xbird

Cursor / Windsurf — .cursor/mcp.json:

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

Node.js — one-time login

npx @checkra1n/xbird login
claude mcp add xbird -- npx @checkra1n/xbird

How It Works

AI Agent (Claude / Cursor / Windsurf)
  │  MCP stdio
bunx @checkra1n/xbird (local MCP server)
  ├── Twitter API → api.x.com (your residential IP)
  └── x402 payment → xbird server (micropayments only)

Credentials stay on your machine. Only USDC micropayments touch the remote facilitator.

Tools

247 MCP tools across 14 categories. Full list: docs/tools.md (auto-generated from source).

Resource	/unit	Examples
post_read	$0.0025	get_tweet, search_tweets, get_replies
user_read	$0.005	get_user, get_followers, get_user_tweets
owned_read	$0.001	get_home_timeline, get_bookmarks, get_current_user
post_create	$0.0075	post_tweet, reply_to_tweet
interaction_create	$0.0075	like_tweet, follow_user
content_create	$0.005	upload_media

List/search tools bill resource × count upfront (default count=20, max 100). Auto-pagination when count > 20. See src/server/config/resources.ts for the full catalog.

CLI

121 commands for direct terminal use:

bunx @checkra1n/xbird whoami
bunx @checkra1n/xbird tweet "hello"
bunx @checkra1n/xbird search "AI agents" --json

REST API

Stateless HTTP API with encrypted credentials per request:

npx @checkra1n/xbird login   # generates encryption key + wallet
curl https://xbirdapi.up.railway.app/api/search?q=AI+agents \
  -H "X-Encryption-Key: <your-token>"

Payments

Micropayments via x402 on Base (USDC). Wallet auto-generated at ~/.config/xbird/wallet.json on first run.

Programmatic use

import { XClient } from "@checkra1n/xbird/client";
import { resolveCredentials } from "@checkra1n/xbird/auth";

Development

bun install
bun test              # unit tests
bun run ci            # tests + regenerate docs/tools.md
bun run docs:tools    # refresh tool list
bun run check         # TypeScript (src + tests)

See CONTRIBUTING.md.

License

MIT