# 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

```bash
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:

```bash
# 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)

```bash
python scripts/auth_flow.py
```

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

### 4. Add to Claude Code

```bash
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)

```bash
# 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:
```bash
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