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)

X API — Social

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