xbird-mcp 0.1.3

package/README.md

@@ -0,0 +1,135 @@
+# xbird-mcp — Twitter/X MCP Server with x402 Micropayments
+
+MCP server that gives AI agents (Claude, Cursor, Windsurf) **30 Twitter/X tools** — reading, searching, posting, engagement, media upload — with per-call x402 micropayments on Base.
+
+Runs locally on your machine using your Twitter cookies, so requests come from a residential IP (no datacenter blocks).
+
+## How It Works
+
+```
+AI Agent (Claude Code / Cursor / Windsurf)
+  |  MCP stdio
+xbird-mcp (local process)
+  |-- Pay x402 --> xbird server (payment gateway)
+  '-- Execute --> Twitter API (your local IP)
+```
+
+The xbird server only verifies payments. All Twitter API calls happen locally from your machine.
+
+## Install
+
+```bash
+bunx xbird-mcp
+# or
+npx xbird-mcp
+```
+
+No global install needed — `bunx`/`npx` runs it directly.
+
+## Setup
+
+### Claude Code
+
+Add to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "xbird": {
+      "command": "bunx",
+      "args": ["xbird-mcp"],
+      "env": {
+        "XBIRD_AUTH_TOKEN": "your_auth_token",
+        "XBIRD_CT0": "your_ct0",
+        "XBIRD_PRIVATE_KEY": "0x_your_wallet_private_key"
+      }
+    }
+  }
+}
+```
+
+### Cursor / Windsurf
+
+Same config in the MCP settings section of your IDE.
+
+## Getting Twitter Cookies
+
+1. Open [x.com](https://x.com) in your browser
+2. DevTools -> Application -> Cookies -> `https://x.com`
+3. Copy `auth_token` and `ct0` values
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `XBIRD_AUTH_TOKEN` | Yes | Twitter `auth_token` cookie |
+| `XBIRD_CT0` | Yes | Twitter `ct0` cookie |
+| `XBIRD_PRIVATE_KEY` | Yes | Wallet private key for USDC payments (Base network) |
+| `XBIRD_SERVER_URL` | No | Payment server URL (default: xbird production server) |
+
+## Tools (30)
+
+### Read — $0.001/call
+
+| Tool | Description |
+|------|-------------|
+| `get_tweet` | Get a tweet by ID |
+| `get_thread` | Get a tweet thread (conversation chain) |
+| `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` | Like a tweet |
+| `unlike_tweet` | Unlike a tweet |
+| `retweet` | Retweet a tweet |
+| `unretweet` | Remove a retweet |
+| `bookmark_tweet` | Bookmark a tweet |
+| `unbookmark_tweet` | Remove a bookmark |
+| `follow_user` | Follow a user |
+| `unfollow_user` | Unfollow a user |
+
+### 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](https://www.x402.org/) on Base (L2). You need a wallet with USDC on Base.
+
+Prices range from $0.001 (reading a tweet) to $0.05 (uploading media).
+
+## License
+
+MIT