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 check         # TypeScript (src + tests; can be memory-heavy)
bun run ci            # tests + regenerate docs/tools.md
bun run ci:local      # same local gate as GitHub CI, including pack audit
bun run docs:tools    # refresh tool list

CI runs automatically on every branch push and pull request. In Cursor, the project hook in .cursor/hooks/auto-ci.sh also runs bun run ci:local at agent stop when code, tests, workflow, or package files changed.

See CONTRIBUTING.md.

License

MIT