# Spectre

**Full X/Twitter automation for AI agents.** Search, post, engage, manage — all through MCP. No paid API keys, no browser automation.

```
pip install spectre-mcp
```

## What It Does

Spectre gives AI agents complete control over X/Twitter:

- **Search** any tweet, user, or trend with full query operators
- **Post** tweets, replies, and quotes
- **Engage** — like, retweet, bookmark, follow/unfollow, mute/unmute, block/unblock
- **Read** profiles, timelines, threads, communities, lists, media
- **Manage** multiple accounts with automatic rotation

42 tools. One MCP server. Works with Hermes, Claude, Cursor, and any MCP client.

## Tools (42)

### Read (20)

| Tool | Description |
|------|-------------|
| `search(query, limit, mode)` | Search tweets. mode: `latest`, `top`, `media` |
| `search_users(query, limit)` | Search users by name/keyword |
| `get_user(username)` | User profile by @handle |
| `get_user_tweets(username, limit)` | User's recent tweets |
| `get_user_media(username, limit)` | User's photos/videos/GIFs |
| `get_followers(username, limit)` | User's followers |
| `get_following(username, limit)` | Who a user follows |
| `get_tweet(tweet_id)` | Single tweet by ID (with media URLs) |
| `get_tweet_replies(tweet_id, limit)` | Replies to a tweet |
| `get_thread(tweet_id, limit)` | Full conversation thread |
| `get_retweeters(tweet_id, limit)` | Users who retweeted |
| `get_trends(category, limit)` | Trending topics |
| `get_list_timeline(list_id, limit)` | Tweets from a list |
| `get_list_members(list_id, limit)` | Members of a list |
| `get_community_tweets(community_id, limit)` | Community feed |
| `get_community_info(community_id)` | Community details |
| `get_bookmarks(limit)` | Your bookmarked tweets |
| `add_account_cookies(username, cookies)` | Add account via cookies |
| `add_account_credentials(user, pass, email, email_pass)` | Add account via login |
| `pool_status()` | Account pool health |

### Write (22)

| Tool | Description |
|------|-------------|
| `post_tweet(text, reply_to?, quote_tweet?)` | Post a tweet |
| `delete_tweet(tweet_id)` | Delete a tweet |
| `like_tweet(tweet_id)` | Like a tweet |
| `unlike_tweet(tweet_id)` | Unlike a tweet |
| `retweet(tweet_id)` | Retweet |
| `unretweet(tweet_id)` | Undo retweet |
| `bookmark_tweet(tweet_id)` | Bookmark |
| `unbookmark_tweet(tweet_id)` | Remove bookmark |
| `follow_user(user_id)` | Follow a user |
| `unfollow_user(user_id)` | Unfollow a user |
| `mute_user(user_id)` | Mute a user |
| `unmute_user(user_id)` | Unmute a user |
| `block_user(user_id)` | Block a user |
| `unblock_user(user_id)` | Unblock a user |
| `get_home_timeline(limit)` | Home timeline feed |
| `send_dm(user_id, text)` | Send a direct message |
| `create_list(name, description)` | Create a new list |
| `update_list(list_id, name, description)` | Update list details |
| `add_list_member(list_id, user_id)` | Add user to list |
| `remove_list_member(list_id, user_id)` | Remove user from list |
| `join_community(community_id)` | Join a community |
| `leave_community(community_id)` | Leave a community |

## Quick Start

### 1. Install

```bash
# With uvx (recommended for MCP)
uvx spectre-mcp

# Or pip
pip install spectre-mcp

# Or from source
git clone https://github.com/pranrichh/spectre.git
cd spectre
uv sync
```

### 2. Add an Account

Grab cookies from your browser (DevTools → Application → Cookies → x.com):
- `auth_token` cookie value
- `ct0` cookie value

```bash
# Via twscrape CLI
twscrape add_cookie my_account "auth_token=xxx; ct0=yyy"

# Or via the MCP tool (once server is running)
add_account_cookies("my_account", "auth_token=xxx; ct0=yyy")
```

### 3. Configure Your MCP Client

**Hermes Agent** (`~/.hermes/config.yaml`):

```yaml
mcp_servers:
  spectre:
    command: "uvx"
    args: ["spectre-mcp"]
    timeout: 120
```

Tools appear as `mcp_spectre_search`, `mcp_spectre_get_user`, etc.

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "spectre": {
      "command": "uvx",
      "args": ["spectre-mcp"]
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "spectre": {
      "command": "uvx",
      "args": ["spectre-mcp"]
    }
  }
}
```

## Hermes Agent Integration

Spectre integrates natively with Hermes Agent. Once configured, all 30 tools are available in every conversation — CLI, Discord, Telegram, etc.

### Configuration

Add to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  spectre:
    command: "uvx"
    args: ["spectre-mcp"]
    timeout: 120
    connect_timeout: 60
```

### How It Works

1. Hermes starts → discovers `spectre` in `mcp_servers`
2. Spawns `uvx spectre-mcp` as a subprocess (stdio transport)
3. Discovers all 30 tools and registers them as `mcp_spectre_*`
4. Tools are available in every conversation automatically

### Tool Naming

All tools are prefixed: `mcp_spectre_{tool_name}`

| MCP Tool Name | What It Does |
|---------------|-------------|
| `mcp_spectre_search` | Search tweets with X query operators |
| `mcp_spectre_get_user` | Get user profile |
| `mcp_spectre_post_tweet` | Post a tweet |
| `mcp_spectre_like_tweet` | Like a tweet |
| `mcp_spectre_retweet` | Retweet |
| `mcp_spectre_follow_user` | Follow a user |
| `mcp_spectre_mute_user` | Mute a user |
| `mcp_spectre_block_user` | Block a user |
| ... | (all 42 tools) |

### Usage Examples

Once configured, just ask Hermes:

- "Search Twitter for AI news from the last week"
- "Get Elon Musk's latest tweets"
- "Post a tweet saying hello world"
- "What's trending on X right now?"
- "Get the full thread from this tweet"
- "Like all tweets from @openai about GPT-5"
- "Follow everyone who retweeted my latest post"

### Account Setup

Add accounts directly through Hermes:

```
Use mcp_spectre_add_account_cookies:
  username: "myaccount"
  cookies: "auth_token=xxx; ct0=yyy"
```

Or via the CLI:

```bash
twscrape add_cookie my_account "auth_token=xxx; ct0=yyy"
```

### Environment Variables

Custom config via `env`:

```yaml
mcp_servers:
  spectre:
    command: "uvx"
    args: ["spectre-mcp"]
    env:
      SPECTRE_PROXY: "socks5://user:pass@host:port"
      TWS_HTTP_BACKEND: "curl"
      TWS_TELEMETRY: "0"
    timeout: 120
```

### Proxies

For high-volume use or avoiding rate limits:

```yaml
mcp_servers:
  spectre:
    command: "uvx"
    args: ["spectre-mcp"]
    env:
      SPECTRE_PROXY: "socks5://user:pass@proxy:port"
```

### Multiple Accounts

Add multiple accounts for automatic rotation:

```bash
twscrape add_cookie account1 "auth_token=xxx; ct0=yyy"
twscrape add_cookie account2 "auth_token=aaa; ct0=bbb"
twscrape add_cookie account3 "auth_token=ccc; ct0=ddd"
```

When one account gets rate-limited, Spectre automatically switches to the next.

## X Query Operators

The `search` tool supports all X search operators:

| Operator | Example | Description |
|----------|---------|-------------|
| `from:username` | `from:elonmusk` | Tweets by a user |
| `since:YYYY-MM-DD` | `since:2026-01-01` | After date |
| `until:YYYY-MM-DD` | `until:2026-06-01` | Before date |
| `#hashtag` | `#python` | Hashtag search |
| `filter:media` | `AI filter:media` | Only media tweets |
| `filter:links` | `AI filter:links` | Only tweets with links |
| `lang:en` | `AI lang:en` | Language filter |
| `min_retweets:N` | `AI min_retweets:100` | Minimum retweets |
| `min_faves:N` | `AI min_faves:50` | Minimum likes |
| `-"term"` | `AI -"GPT"` | Exclude term |
| `OR` | `python OR rust` | Either term |

Combine operators: `from:openai filter:media since:2026-01-01 lang:en`

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `SPECTRE_DB` | `~/.twscrape/spectre.db` | Account pool SQLite path |
| `SPECTRE_PROXY` | none | Global proxy (`socks5://user:pass@host:port`) |
| `TWS_HTTP_BACKEND` | `httpx` | Set to `curl` for TLS fingerprinting |
| `TWS_PROXY` | none | Alternative proxy env (lower priority) |
| `TWS_TELEMETRY` | `0` | Disable telemetry |
| `SPECTRE_OP_*` | built-in | Override GraphQL operation IDs |

## How It Works

Spectre talks directly to X's internal GraphQL API — the same endpoints X's own web app uses. No browser automation, no paid developer API.

- **Account pool** — multiple accounts rotate automatically when one hits rate limits
- **Session management** — cookie-based auth persists across restarts
- **Transaction IDs** — generates valid `x-client-transaction-id` headers for write operations
- **Rate limit tracking** — per-endpoint, per-account, with automatic cooldown

## Account Pool

Best practice: 2-3 throwaway accounts from separate browser sessions. Never use your main account.

```bash
# Check pool health
twscrape stats

# Or via MCP
pool_status()
```

## Limitations

- **Requires authenticated accounts** — X blocks unauthenticated access
- **Rate limited** — ~300 requests/hour/account (rotation handles this)
- **~3200 tweet cap** on user timelines (X's own limit)
- **Operation IDs rotate** — GraphQL mutation IDs change every few months. Update via env vars (`SPECTRE_OP_CREATE_TWEET`, etc.)
- **ToS risk** — automated access violates X's terms. Write operations carry higher ban risk.

## Development

```bash
git clone https://github.com/pranrichh/spectre.git
cd spectre
uv sync
uv run python -m spectre.server
```

## License

MIT