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