How do I use x-ai-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@x-ai-mcp analyze the current sentiment around AI agents on X" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

x-ai-mcp

by olivier-motium

Overview Schema Source Related Servers Discussions Admin

Python

Remote

x-ai-mcp

X (Twitter) MCP server with Grok-powered intelligence. Personal account access + AI analysis in one package.

20 tools: 16 X API tools for reading/writing + 4 Grok intelligence tools for real-time analysis.

Setup

1. Install

git clone https://github.com/olivier-motium/x-ai-mcp.git
cd x-ai-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

2. Configure

Copy .env.example to .env and fill in:

# Required — X API bearer token (read-only operations)
X_BEARER_TOKEN=your_bearer_token

# Required — your X user ID
X_USER_ID=your_user_id

# Optional — OAuth for write ops (posting, DMs)
# Run: python scripts/auth_flow.py
X_CLIENT_ID=your_client_id

# Optional — xAI key for intelligence tools
XAI_API_KEY=your_xai_key

3. Get OAuth tokens (for write operations)

python scripts/auth_flow.py

Opens browser, authorizes your account, saves token.json. Tokens auto-refresh.

4. Add to Claude Code

claude mcp add x-ai \
  -e X_BEARER_TOKEN=xxx \
  -e X_USER_ID=xxx \
  -e XAI_API_KEY=xxx \
  -- python -m src.server

Tools

X API — Timeline & Tweets

Tool	Description
`x_home_timeline`	Your home timeline
`x_user_tweets`	A user's recent tweets
`x_get_tweet`	Get a specific tweet
`x_post_tweet`	Post a tweet (OAuth)
`x_delete_tweet`	Delete your tweet (OAuth)
`x_search_tweets`	Search recent tweets (7 days)

X API — DMs

Tool	Description
`x_list_dms`	Recent DM messages
`x_read_dm`	Read a DM conversation
`x_send_dm`	Send a DM (OAuth)

Tool	Description
`x_bookmarks`	Your bookmarked tweets
`x_liked_tweets`	Liked tweets (you or others)
`x_like_tweet`	Like a tweet (OAuth)
`x_user_info`	User profile details
`x_followers`	List followers
`x_following`	List following

Intelligence — Grok-powered

Tool	Description
`x_analyze_topic`	Real-time analysis of any topic on X
`x_daily_digest`	AI-powered daily briefing
`x_summarize_thread`	Summarize a tweet thread
`x_analyze_account`	Deep analysis of any X account

Daily Digest (standalone)

# Default (AI/tech focus)
python scripts/daily_digest.py

# Custom focus
python scripts/daily_digest.py --focus "crypto markets"

# Save to file
python scripts/daily_digest.py --focus "AI agents" --output digest.md

Cron it for daily briefings:

0 9 * * * cd /path/to/x-ai-mcp && .venv/bin/python scripts/daily_digest.py >> ~/digests.log

Architecture

Bearer Token (read) ──┐
OAuth 2.0 PKCE (r/w) ─┤──→ X API v2 ──→ 16 MCP tools
                       │
xAI API Key ───────────┤──→ Grok (x_search + chat) ──→ 4 intelligence tools
                       │
Logfire (optional) ────┘──→ Observability dashboard

X client: async httpx, auto rate-limit retry, OAuth token refresh
Grok client: Chat Completions API for analysis, Responses API with x_search for real-time X data
Output: Plain text, never raw JSON. Tweets formatted as [date time] @user: text (metrics)

License

MIT

Available Tools

23 tools

x_analyze_accountB

Use Grok to analyze an X account — their posting patterns, key topics, influence, and recent activity.

Args:
    username: X username (without @)

Inputs: username (required). Returns: result

x_analyze_topicB

Use Grok AI to analyze what X is saying about a topic right now. Returns insights with citations from real-time X data.

Args:
    topic: Topic to analyze (e.g., 'AI agents', 'Claude Code', 'Bitcoin')

Inputs: topic (required). Returns: result

x_bookmarksB

Get your bookmarked tweets. Requires OAuth token.

Args:
    count: Number of bookmarks (1-100, default 20)

Inputs: count. Returns: result

x_daily_digestB

Generate an AI-powered daily digest of what's happening on X. Uses Grok with real-time X search.

Args:
    focus: Optional focus area (e.g., 'AI', 'crypto', 'tech startups'). Defaults to general tech/AI.

Inputs: focus. Returns: result

x_delete_tweetA

Delete one of your tweets. Permanent action.

Args:
    tweet_id: ID of the tweet to delete

Inputs: tweet_id (required). Returns: result

x_dm_inboxA

List all DM conversations — both regular (REST API) and encrypted (XChat GraphQL).

Shows conversation list with participant info, last message preview,
and encryption status. Encrypted conversations are fetched from XChat
and decrypted if private key is available.

Args:
    count: Max conversations to return (default 20)

Inputs: count. Returns: result

x_dm_read_conversationA

Read messages from a DM conversation.

Automatically detects encrypted conversations (IDs starting with 'e')
and uses XChat GraphQL + decryption. Regular conversations use REST API.

Args:
    conversation_id: The conversation ID
    count: Max messages to fetch (default 50)

Inputs: conversation_id (required), count. Returns: result

x_dm_sendB

Send a DM via X's internal API (regular conversations only).

Args:
    conversation_id: The conversation ID to send to
    text: Message text to send

Inputs: conversation_id (required), text (required). Returns: result

x_followersB

List followers for yourself or another user.

Args:
    username: Username or user ID (default: your account)
    count: Number of followers (1-1000, default 50)

Inputs: username, count. Returns: result

x_followingB

List accounts you (or another user) follow.

Args:
    username: Username or user ID (default: your account)
    count: Number of accounts (1-1000, default 50)

Inputs: username, count. Returns: result

x_get_tweetA

Get a specific tweet by ID with full details.

Args:
    tweet_id: The tweet ID to fetch

Inputs: tweet_id (required). Returns: result

x_home_timelineA

Get your home timeline — tweets from people you follow. Requires OAuth token.

Args:
    count: Number of tweets to fetch (1-100, default 20)

Inputs: count. Returns: result

x_liked_tweetsB

Get liked tweets for yourself or another user.

Args:
    username: Username or user ID (default: your account)
    count: Number of likes (1-100, default 20)

Inputs: username, count. Returns: result

x_like_tweetB

Like a tweet. Requires OAuth token.

Args:
    tweet_id: ID of the tweet to like

Inputs: tweet_id (required). Returns: result

x_list_dmsA

List your actual DM conversations (where you've replied). Filters out unanswered message requests.

Args:
    count: Number of DM events to scan (1-100, default 50). Higher = more conversations found.

Inputs: count. Returns: result

x_message_requestsB

List pending DM message requests — messages from people you haven't replied to.

Args:
    count: Number of DM events to scan (1-100, default 50).

Inputs: count. Returns: result

x_post_tweetA

Post a new tweet. Requires OAuth token with tweet.write scope.

Args:
    text: Tweet text (max 280 characters)
    reply_to: Optional tweet ID to reply to

Inputs: text (required), reply_to. Returns: result

x_read_dmB

Read messages from a specific DM conversation.

Args:
    conversation_id: The DM conversation ID
    count: Number of messages (1-100, default 20)

Inputs: conversation_id (required), count. Returns: result

x_search_tweetsA

Search recent tweets (last 7 days). Supports X search operators.

Args:
    query: Search query. Supports operators like 'from:user', 'has:links', '#hashtag', '-filter:retweets'
    count: Number of results (10-100, default 20)

Inputs: query (required), count. Returns: result

x_send_dmA

Send a direct message to a user. Requires OAuth with dm.write scope.

Args:
    user_id: The recipient's user ID
    text: Message text

Inputs: user_id (required), text (required). Returns: result

x_summarize_threadB

Use Grok to find and summarize a tweet thread. Provides key points and analysis.

Args:
    tweet_id: ID of the first tweet in the thread (or any tweet in it)

Inputs: tweet_id (required). Returns: result

x_user_infoB

Get detailed profile info for a user.

Args:
    username: X username (without @) or user ID

Inputs: username (required). Returns: result

x_user_tweetsB

Get recent tweets from a specific user.

Args:
    username: X username (without @) or user ID
    count: Number of tweets (1-100, default 20)

Inputs: username (required), count. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored 2026-04-18 06:15 across 23 tools

Disambiguation4/5

Most tools have distinct purposes with clear boundaries, such as x_analyze_account for account analysis and x_post_tweet for tweeting. However, there is some overlap between x_dm_inbox and x_list_dms (both list DM conversations) and between x_dm_send and x_send_dm (both send DMs), which could cause minor confusion for an agent.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with a clear 'x_' prefix, and most use descriptive verb_noun combinations (e.g., x_analyze_account, x_search_tweets). The naming is highly predictable and uniform across all 23 tools.

Tool Count3/5

With 23 tools, the count is on the higher side for a Twitter/X-focused server, bordering on heavy. While it covers many aspects of the platform, it might feel overwhelming or slightly over-scoped compared to more streamlined servers, but it's not extreme.

Completeness5/5

The tool set provides comprehensive coverage for the Twitter/X domain, including account analysis, tweeting (post, delete, like), DMs (send, read, manage), user info, timelines, search, and advanced features like summarization and digests. There are no obvious gaps, and it supports full CRUD-like operations for tweets and DMs.

Resources

Related MCP Connectors

X (Twitter) MCP by InsightfulPipeA
com.insightfulpipe
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Social Media Communication
41
https://x-organic.insightfulmcp.com/
TwitterAPIs
io.github.TwitterAPIs
Official MCP server for twitterapis.com. Twitter/X search, users, DMs, Grok, monitoring and writes.
Social Media Communication Search
16
https://api.twitterapis.com/mcp
twitterapi-mcp-serverA
io.github.kaitoInfra
Twitter/X read-only MCP server — 12 tools: search, users, tweets, followers, timelines, trends.
Social Media Search
121
https://mcp.twitterapi.io/mcp
mcp-serverA
io.twitterapi
Official twitterapi.io hosted MCP: Twitter/X tweets, users, followers, trends. OAuth or API key.
Social Media Search
121
https://mcp.twitterapi.io/v1/mcp

Appeared in Searches

Servers for Salesforce, LinkedIn, Instagram, X (Twitter), and Financial Trading/Arbitrage

x-ai-mcp

Setup

1. Install

2. Configure

3. Get OAuth tokens (for write operations)

4. Add to Claude Code

Tools

X API — Timeline & Tweets

X API — DMs

X API — Social

Intelligence — Grok-powered

Daily Digest (standalone)

Architecture

License

Available Tools

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Appeared in Searches