Overview

xbird provides 34 MCP tools to let AI agents tweet, read timelines, search tweets, check mentions, manage engagement, and update profiles or media on Twitter/X. It runs locally from a residential IP and uses micropayments for tool calls, enabling controlled, auditable interactions with the platform.

How This Skill Works

xb ird exposes tool groups: Read, Search, Bulk, Write, Profile, and Media. An agent authenticates with XBIRD_AUTH_TOKEN, XBIRD_CT0, and optionally XBIRD_PRIVATE_KEY, then calls the appropriate MCP endpoints (e.g., get_tweet, search_tweets, post_tweet, upload_media). Each action consumes a micropayment per the tool’s defined cost, and results are returned for downstream decision making.

When to Use It

• Post a tweet or create a multi-part thread, possibly with media attached.
• Read or monitor tweets, timelines, replies, or mentions to inform next actions.
• Search for tweets and user mentions to respond or engage with specific topics.
• Manage engagement by liking, retweeting, or bookmarking tweets, or following users.
• Update profile information (bio, avatar, banner) or upload media for posts.

Quick Start

1. Step 1: Set up xbird MCP server and authenticate (claude mcp add xbird -- npx @checkra1n/xbird; configure XBIRD_AUTH_TOKEN, XBIRD_CT0, and optional XBIRD_PRIVATE_KEY).
2. Step 2: Upload media you want to attach, then post a tweet with the returned mediaIds or create a thread with post_thread.
3. Step 3: Validate results, adjust query or actions, and monitor costs per call to stay within micropayment limits.

Best Practices

• Fetch context first (e.g., get_user or get_home_timeline) before posting or engaging to ensure relevant targeting.
• When posting media, upload_media first to obtain a mediaId and pass it in post_tweet or post_thread.
• For threads, use post_thread with a minimum of two tweets and ensure the array order preserves narrative flow.
• Use numeric userIds for bulk reads (get_user_tweets, get_followers, etc.) and verify handles when following/unfollowing.
• Keep credentials secure (XBIRD_AUTH_TOKEN/CT0) and monitor usage against micropayment costs and rate limits.

Example Use Cases

• Upload an image and post a tweet with the media attached using upload_media followed by post_tweet with mediaIds.
• Create a 3-tweet thread about a product update using post_thread and include multiple media items if needed.
• Fetch a target user’s recent tweets by resolving their handle to a numeric userId and calling get_user_tweets.
• Search for tweets containing a topic (e.g., AI agents since:2024-01-01 -filter:retweets) and like or retweet selected results.
• Update your profile by uploading a new avatar and changing the bio with update_profile_image and update_profile.

Frequently Asked Questions