# xbird — Complete Documentation

> Twitter/X MCP Server for AI Agents with x402 Micropayments

## Overview

xbird is a Model Context Protocol (MCP) server that provides AI agents with full programmatic access to the Twitter/X platform. Unlike the official Twitter API which requires developer accounts, API keys, and OAuth configuration, xbird uses the x402 micropayment protocol to handle authentication and billing automatically.

When an AI agent makes a tool call, xbird proxies the request to Twitter/X and charges a fraction of a cent via x402. The agent's MCP client handles payment automatically — no human intervention required.

## Architecture

```
AI Agent (Claude, Cursor, etc.)
    ↓ MCP tool call
xbird (local MCP server)
    ↓ HTTP request
Twitter/X API
    ↑ response
xbird
    ↑ MCP tool result
AI Agent
```

Payment flow:
1. Agent calls an MCP tool (e.g., search_tweets)
2. xbird responds with HTTP 402 + price (dual accepts: Base USDC and X Layer USDT)
3. Client signs payment — default: local wallet + USDC on Base via @x402/fetch; optional: OKX Agentic Wallet via onchainos
4. xbird verifies payment and executes the Twitter API call
5. Results returned to agent

### Payment modes (MCP local)

| Mode | Env | Description |
|------|-----|-------------|
| Default | *(none)* | Auto wallet + USDC on Base |
| Agentic | `XBIRD_PAYMENT_MODE=agentic` | OKX Agentic Wallet only |
| Auto | `XBIRD_PAYMENT_MODE=auto` | Agentic when logged in, else Base fallback |

Rail selection (agentic/auto): `XBIRD_PAYMENT_RAIL=base|xlayer|auto`

## Installation

### Claude Code (recommended)
```bash
claude mcp add xbird -- npx @checkra1n/xbird
```

### Claude Desktop / Cursor / Windsurf
Add as MCP server with command: `npx @checkra1n/xbird`

### Global install
```bash
npm install -g @checkra1n/xbird
```

### Smithery
```bash
npx -y @smithery/cli install @checkra1neth/xbirdmcp
```

### Requirements
- Node.js 18+ or Bun 1.0+
- Internet connection
- An MCP-compatible AI agent with x402 payment support

## Complete Tool Reference

Billing: **resource rate × count** (default count 20, max 100). List/search tools auto-paginate when count > 20. Rates ~2× lower than X API pay-per-use.

### post_read ($0.0025/unit)

**get_tweet**
Get a tweet by its ID. Returns full tweet data including text, author, engagement metrics, media, and metadata.
Parameters: id (string, required) — Tweet ID

**get_thread**
Get a complete tweet thread (conversation chain). Returns all tweets in the thread in order.
Parameters: id (string, required) — Tweet ID of any tweet in the thread

**get_replies**
Get replies to a specific tweet.
Parameters: id (string, required), count (number, optional, default 20), cursor (string, optional)

**get_user**
Get a Twitter user's profile by their handle.
Parameters: handle (string, required) — Twitter handle without @

**get_user_about**
Get detailed about information for a user including bio, location, join date, and more.
Parameters: handle (string, required)

**get_current_user**
Get the authenticated user's profile. No parameters required.

**get_home_timeline**
Get the home timeline (latest tweets from followed accounts).
Parameters: count (number, optional, default 20), cursor (string, optional)

**get_news**
Get trending news and topics on Twitter.
Parameters: tab (string, optional — trending/forYou/news/sports/entertainment), count (number, optional), aiOnly (boolean, optional)

**get_lists**
Get Twitter lists owned by the authenticated user. No parameters required.

**get_list_timeline**
Get tweets from a specific Twitter list.
Parameters: id (string, required — List ID), count (number, optional, default 20), cursor (string, optional)

### post_read — search & mentions ($0.0025/unit, count-aware)

**search_tweets**
Search for tweets using full-text search.
Parameters: query (string, required), count (number, optional, default 20), cursor (string, optional)

**get_mentions**
Get mentions for a specific user.
Parameters: handle (string, required), count (number, optional)

### user_read ($0.005/unit, count-aware on lists)

**get_user_tweets**
Get tweets posted by a user.
Parameters: userId (string, required — numeric user ID), count (number, optional, default 20), cursor (string, optional)

**get_followers**
Get a user's followers.
Parameters: userId (string, required), count (number, optional, default 20), cursor (string, optional)

**get_following**
Get users that a user follows.
Parameters: userId (string, required), count (number, optional, default 20), cursor (string, optional)

**get_likes**
Get tweets liked by a user.
Parameters: userId (string, required), count (number, optional, default 20), cursor (string, optional)

**get_bookmarks**
Get bookmarked tweets.
Parameters: count (number, optional, default 20), cursor (string, optional), folderId (string, optional)

**get_list_memberships**
Get lists the authenticated user is a member of. No parameters required.

### post_create & interaction_create ($0.0075/unit)

**post_tweet**
Post a new tweet.
Parameters: text (string, required), mediaIds (string[], optional)

**reply_to_tweet**
Reply to an existing tweet.
Parameters: text (string, required), replyToId (string, required), mediaIds (string[], optional)

**post_thread**
Post a thread (multiple tweets in sequence).
Parameters: texts (string[], required, minimum 2 items)

**like_tweet**
Like a tweet.
Parameters: tweetId (string, required)

**unlike_tweet**
Unlike a tweet.
Parameters: tweetId (string, required)

**retweet**
Retweet a tweet.
Parameters: tweetId (string, required)

**unretweet**
Remove a retweet.
Parameters: tweetId (string, required)

**bookmark_tweet**
Bookmark a tweet.
Parameters: tweetId (string, required)

**unbookmark_tweet**
Remove a bookmark.
Parameters: tweetId (string, required)

**follow_user**
Follow a Twitter user.
Parameters: handle (string, required)

**unfollow_user**
Unfollow a Twitter user.
Parameters: handle (string, required)

### content_create ($0.005/unit)

**upload_media**
Upload an image or video for use in tweets. Returns a mediaId to pass to post_tweet or reply_to_tweet.
Parameters: filePath (string, required — absolute path to file), alt (string, optional — alt text for accessibility)

## Pricing Details

| Resource | Rate/unit | Count-aware | Example tools |
|----------|-----------|-------------|---------------|
| post_read | $0.0025 | yes (default 20, max 100) | get_tweet, search_tweets, get_replies |
| user_read | $0.005 | yes | get_user, get_followers, get_user_tweets |
| owned_read | $0.001 | yes | get_home_timeline, get_bookmarks |
| post_create | $0.0075 | no | post_tweet, reply_to_tweet |
| interaction_create | $0.0075 | no | like_tweet, follow_user |
| content_create | $0.005 | no | upload_media |

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

### Cost comparison (same 9-call session, count=20 on search/lists)
- xbird: ~$0.13 (resource × count billing)
- X API pay-per-use: ~$0.26 (~2× more expensive)

Both bill per resource unit. xbird unit rates are ~2× lower than X API. Example: search count=20 costs $0.05 on xbird vs $0.10 on X API; count=100 costs $0.25 vs $0.50.

### X API pay-per-use prices (for reference)
- Posts: Read — $0.005/resource
- User: Read — $0.010/resource
- Following/Followers: Read — $0.010/resource
- DM Event: Read — $0.010/resource
- Content: Create — $0.010/request
- User Interaction: Create — $0.015/request (like, follow, retweet)
- DM Interaction: Create — $0.015/request
- List: Read — $0.005/resource
- Trend: Read — $0.010/resource
- Media Metadata — $0.005/request
- Bookmark — $0.005/request

Plus X API requires a developer account, API keys, and purchasing credits upfront. xbird requires none of that — payment is fully automated via x402.

## Compatibility

| Agent          | Status        |
|---------------|---------------|
| Claude Code    | Supported     |
| Claude Desktop | Supported     |
| Cursor         | Supported     |
| Windsurf       | Supported     |
| Custom MCP     | Supported     |
| OpenAI Agents  | Coming soon   |

## FAQ

Q: Do I need a Twitter developer account?
A: No. xbird handles all Twitter API access. You just install and use it.

Q: How does payment work?
A: xbird uses x402 micropayments. Price = resource rate × count (HTTP 402 matches your request). The API server accepts dual-rail: Base USDC (eip155:8453) and X Layer USDT (eip155:196). MCP default: auto-generated local wallet on Base. Optional: OKX Agentic Wallet via onchainos (XBIRD_PAYMENT_MODE=agentic, XBIRD_PAYMENT_RAIL=xlayer for X Layer).

Q: Does it run on my machine?
A: Yes. xbird runs as a local MCP server on your machine, using your residential IP address.

Q: Is there a rate limit?
A: xbird manages rate limits internally. You don't need to worry about Twitter API rate limits.

Q: Can I use it for automation?
A: Yes. xbird is designed for AI agent automation — posting, engaging, monitoring, and researching on Twitter/X.