Spectre

X/Twitter data for AI agents. MCP server powered by twscrape — direct GraphQL, no browser automation, no paid API keys.

What It Does

Gives AI agents (Hermes, Claude, Cursor, etc.) the ability to:

• Search tweets with full X query operators

• Read user profiles, timelines, media

• Follow conversation threads

• Track trending topics

• Browse communities and lists

• Manage an account pool with automatic rotation

All via X's internal GraphQL API — 10-100x faster than browser-based alternatives.

Related MCP server: Twitter/X MCP Server

Quick Start

1. Install

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

# Or pip
pip install spectre-mcp

2. Add an Account

Grab cookies from your browser (DevTools → Application → Cookies → x.com):

# Via the MCP tool
add_account_cookies("my_account", "auth_token=xxx; ct0=yyy")

Or via twscrape CLI:

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

3. Configure Your MCP Client

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

mcp:
  servers:
    spectre:
      command: uvx
      args: ["spectre-mcp"]

Claude Desktop (claude_desktop_config.json):

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

Cursor (.cursor/mcp.json):

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

Tools (22)

Environment Variables

How It Works

Spectre wraps twscrape behind the Model Context Protocol. twscrape handles:

• GraphQL endpoint management (auto-updated operation IDs)

• x-client-transaction-id generation

• Account pool rotation on rate limits

• Per-endpoint rate limit tracking

• Cookie-based session persistence

Spectre adds:

• Clean MCP tool interface for agent consumption

• Pydantic response models

• Account pool management tools

• Proper error handling and limits

Account Pool

The account pool is a local SQLite database. Accounts are automatically rotated when one gets rate-limited (per-endpoint). If all accounts are locked, Spectre waits until one frees up.

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

Limitations

• Read-only — no posting, liking, following (by design, for research use)

• Requires authenticated accounts — X blocks unauthenticated access

• Rate limited — ~300 requests/hour/account (automatic rotation handles this)

• ~3200 tweet cap on user timelines (X's own limit)

• ToS risk — automated access violates X's terms. Use responsibly.

License

MIT