TwitGhost

A Model Context Protocol (MCP) server for interacting with Twitter/X. Search tweets, post tweets, send DMs, manage your timeline — all through natural language with any MCP client (Claude, Code, Cursor, etc.).

Why TwitGhost? This is a maintained fork of adhikasp/mcp-twikit that uses the unclecode/twikit fork instead of d60/twikit, fixing the KEY_BYTE / Cryptography_Hasher errors that have been blocking authentication with current X API versions.

Features

• Search tweets — by keyword, with Top or Latest sorting

• User timeline — get tweets from any user

• Home timeline — For You and Following feeds

• Post tweets — with media, replies, and mentions

• Delete tweets — by ID

• Send DMs — direct messages with optional media

• Delete DMs — by message ID

Related MCP server: X MCP Server

Installation

Prerequisites

• Python 3.10+

• A Twitter/X account (free tier works fine)

Via Smithery (recommended)

npx -y @smithery/cli install mcp-twitghost --client claude

Manual (uvx)

{
  "mcpServers": {
    "twitghost": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/arvinmoj/mcp-twitghost", "mcp-twitghost"],
      "env": {
        "TWITTER_USERNAME": "@yourusername",
        "TWITTER_EMAIL": "you@example.com",
        "TWITTER_PASSWORD": "your-password"
      }
    }
  }
}

Manual (pip)

git clone https://github.com/arvinmoj/mcp-twitghost.git
cd mcp-twitghost
pip install .

Then configure in your MCP client:

{
  "mcpServers": {
    "twitghost": {
      "command": "mcp-twitghost",
      "env": {
        "TWITTER_USERNAME": "@yourusername",
        "TWITTER_EMAIL": "you@example.com",
        "TWITTER_PASSWORD": "your-password"
      }
    }
  }
}

Authentication

TwitGhost supports two authentication modes, checked in order:

1. Browser Cookies (recommended — bypasses Cloudflare/rate limits)

If you export cookies from your browser session, TwitGhost loads them directly. This bypasses the Cloudflare WAF block that often breaks password login.

Cookie path: ~/.twitghost/cookies.json

How to export:

1. Log in to X in your browser

2. Install a cookie exporter extension (e.g., "Get cookies.txt" or "Export Cookie JSON")

3. Export cookies as JSON to ~/.twitghost/cookies.json

4. Restart your MCP client

Required cookies for a working session:

• auth_token — primary auth

• ct0 — CSRF token

• twid — user ID

• guest_id — guest identifier

• __cf_bm — Cloudflare bypass

Cookies expire ~30 days. When they do, re-export from your browser.

2. Credentials (fallback)

If no cookies file is found, TwitGhost falls back to username/email/password login:

⚠️ Known issue: password login may fail with Cloudflare or KEY_BYTE errors. If this happens, switch to browser cookies.

Available Tools

Rate Limits

Built-in client-side rate limiting to avoid hitting Twitter's server-side caps:

Troubleshooting

KEY_BYTE or Cryptography_Hasher error

This is a known issue with the original d60/twikit package and newer X API endpoints. TwitGhost uses the unclecode/twikit fork which fixes this. Make sure you installed the right dependency:

pip show twikit
# Source should show unclecode/twikit

If it still shows d60/twikit, reinstall:

pip uninstall twikit
pip install git+https://github.com/unclecode/twikit.git

Cloudflare / 403 error on login

Twitter's Cloudflare WAF blocks many automated logins. Use browser cookies instead:

1. Export cookies from a logged-in browser session

2. Save to ~/.twitghost/cookies.json

3. Restart TwitGhost

Cookie file exists but auth fails

Cookies expire after ~30 days. Re-export from your browser.

Cannot connect to host / SSL errors

Ensure your Python installation has up-to-date SSL certificates:

pip install --upgrade certifi

Credits

• Based on adhikasp/mcp-twikit — original MCP Twitter server

• Uses unclecode/twikit fork for X API compatibility

• Built with FastMCP and the MCP protocol

License

MIT