# xbird

> Twitter MCP Server — No Developer Account, No API Keys

xbird is an MCP (Model Context Protocol) server that gives AI agents full access to the Twitter/X API. No Twitter developer account needed, no API keys — you sign in with your browser cookies (auth_token + ct0). Billing matches X API resources (~2× cheaper per unit) via x402 micropayments.

## When to use xbird

- An AI agent needs to **read or search Twitter/X**: tweets, threads, replies, profiles, followers, timelines, bookmarks, lists, communities, DMs.
- An agent needs to **act on Twitter/X**: post tweets, reply, retweet, like, bookmark, follow, send DMs, upload media.
- You want **zero setup** — no developer portal, no OAuth app, no approval wait; the browser session you already have is the credential.
- You want **pay-per-call economics** (~2× cheaper per unit than X API pay-per-use) instead of a monthly subscription.
- You are running Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP client — or you want plain REST / CLI.

## When NOT to use xbird

- You need official X enterprise support/SLAs, historical full-archive search, or advertising APIs — use the official X API for those.
- The caller cannot make on-chain micropayments (x402, USDC on Base).

How an agent should call xbird: install as an MCP server (tools are discovered automatically), or hit the stateless REST API (contract at https://xbird.dev/openapi.json), or shell out to the CLI.

## Install

Claude Code:
  claude mcp add xbird -- bunx @checkra1n/xbird

Claude Desktop / Cursor / Windsurf:
  Add "bunx @checkra1n/xbird" as an MCP server command (or npx for Node.js)

Global install:
  npm install -g @checkra1n/xbird

Smithery:
  npx -y @smithery/cli install @checkra1neth/xbirdmcp

## CLI tool

Published on npm as `@checkra1n/xbird`:
- Package: https://www.npmjs.com/package/@checkra1n/xbird
- Install: `npm install -g @checkra1n/xbird` → `xbird --help`
- 121 commands: `xbird tweet "hello"`, `xbird search "query"`, `xbird timeline`, …

## Resource catalog (price = rate × count)

| Resource | Rate/unit | Count-aware | Example tools |
|----------|-----------|-------------|---------------|
| post_read | $0.0025 | yes (default 20, max 100) | get_tweet, search_tweets, create_grok_conversation |
| user_read | $0.005 | yes | get_user, get_followers, get_user_tweets |
| owned_read | $0.001 | yes | get_home_timeline, get_bookmarks, get_current_user |
| list_read | $0.0025 | yes | get_list, get_list_timeline, search_lists |
| space_read | $0.0025 | no | get_audio_space, get_space |
| community_read | $0.0025 | yes | get_community, search_communities |
| trend_read | $0.005 | yes | get_explore, get_news |
| dm_read | $0.005 | yes | get_dm_conversation, get_dm_inbox |
| post_create | $0.0075 | no | post_tweet, reply_to_tweet, post_thread |
| interaction_create | $0.0075 | no | like_tweet, follow_user, retweet |
| interaction_delete | $0.005 | no | unlike_tweet, delete_tweet, unfollow_user |
| bookmark_create | $0.0025 | no | bookmark_tweet |
| dm_create | $0.0075 | no | send_dm |
| content_create | $0.005 | no | upload_media, update_profile_image |
| list_create | $0.005 | no | create_list, create_community |
| list_manage | $0.0025 | no | add_list_member, create_bookmark_folder |
| privacy_update | $0.005 | no | update_profile |

List/search tools auto-paginate when count > 20 until the billed count is reached.

## Pricing examples

- search_tweets count=20 → post_read × 20 = $0.05 (X API: $0.10)
- search_tweets count=100 → post_read × 100 = $0.25 (X API: $0.50)
- get_tweet → post_read × 1 = $0.0025 (X API: $0.005)
- post_tweet → post_create × 1 = $0.0075 (X API: $0.015)

Example session (9 calls, count=20 on search/lists): ~$0.13 total vs ~$0.26 on X API pay-per-use.

Both xbird and X API bill per resource unit — xbird unit rates are ~2× lower. No developer account, no API keys, no credits to purchase.

## How It Works

1. Install xbird as an MCP server (one command)
2. Set your Twitter cookies (auth_token + ct0) as env vars — or auto-detect with Bun
3. Your AI agent discovers and calls tools automatically
4. x402 handles payment inline via HTTP 402 — amount matches resource × count
5. xbird executes the Twitter API call and returns results

## Payment (x402 dual-rail)

**Default (unchanged):** local wallet at `~/.config/xbird/wallet.json` + USDC on Base. No extra setup.

**Optional — OKX Agentic Wallet (v0.4.3+):**
- `XBIRD_PAYMENT_MODE=agentic|auto` (default: `base`)
- `XBIRD_PAYMENT_RAIL=base|xlayer|auto` (agentic/auto only)
- Install: `npx skills add okx/onchainos-skills` → `onchainos wallet login`
- Server accepts **Base** (`eip155:8453`, USDC) and **X Layer** (`eip155:196`, USDT)

## Key Features

- No Twitter developer account required
- No API keys — uses your browser session cookies (auth_token + ct0)
- ~2× cheaper than X API on comparable pay-per-use resources
- Setup in 30 seconds with one command
- Runs locally from your residential IP
- Works with Claude Code, Claude Desktop, Cursor, Windsurf
- 248 MCP tools across 17 X API–aligned resource types
- 121 CLI commands for direct terminal use
- Auto-pagination for count > 20 on list/search tools
- x402 micropayment protocol (pay only for what you use)
- Dual-rail payments: Base USDC (default) or X Layer USDT via Agentic Wallet (opt-in)

## REST API

Base URL: `https://xbirdapi.up.railway.app`

Stateless HTTP API with the same resource billing. Hosted `/mcp` is disabled by default — use local MCP or `XBIRD_ENABLE_REMOTE_MCP=1`.

No signup and no API keys: paid calls authenticate via the x402 `X-PAYMENT` header (handled automatically by x402 clients); Twitter credentials travel per-request in `X-Twitter-Auth-Token` + `X-Twitter-CT0` headers or an encrypted token from `POST /api/accounts`.

Free tier — these require no payment and no credentials:
- `GET /health` — liveness
- `GET /api/authorize/:resource/:units` — exact price dry-run
- All `/.well-known/*` metadata documents
- `GET /openapi.json` — machine-readable API contract

Errors are structured JSON: `{"error":{"code","message","resolution"}}`.

Authorize upfront: `POST /api/authorize/:resource/:units`

## Why xbird vs other Twitter MCP servers?

Most Twitter MCP servers require a Twitter developer account and 4-7 API credentials. xbird works with browser cookies — no Developer Portal, no OAuth app, no approval wait.

## Links

- [Agent instructions (when-to-use)](https://xbird.dev/agent-instructions.md)
- [OpenAPI spec](https://xbird.dev/openapi.json)
- [MCP manifest](https://xbird.dev/.well-known/mcp.json)
- [Protected resource metadata](https://xbird.dev/.well-known/oauth-protected-resource.json)
- [Docs (markdown)](https://xbird.dev/docs.md)
- [Full docs (markdown)](https://xbird.dev/llms-full.txt)
- [Homepage (markdown)](https://xbird.dev/index.md)
- [About](https://xbird.dev/about.md) · [Contact](https://xbird.dev/contact.md) · [Privacy](https://xbird.dev/privacy.md) · [Security](https://xbird.dev/security.md)
- [Sitemap](https://xbird.dev/sitemap.xml)
- [xbird website](https://xbird.dev)
- [npm package](https://www.npmjs.com/package/@checkra1n/xbird)
- [GitHub repository](https://github.com/checkra1neth/xbird)
- [Smithery server](https://smithery.ai/server/checkra1neth/xbirdmcp)
- [Agent Skill](https://github.com/checkra1neth/xbird-skill)