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.

Related MCP server: Twitter/X MCP Server

Tools (42)

Read (20)

Write (22)

Quick Start

1. Install

# 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

# 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):

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):

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

Cursor (.cursor/mcp.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:

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}

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:

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

Environment Variables

Custom config via env:

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:

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

Multiple Accounts

Add multiple accounts for automatic rotation:

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:

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

Environment Variables

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.

# 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

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

License

MIT