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

---

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:

Env Variable	Description	Required
TWITTER_USERNAME	Your X handle	Yes
TWITTER_EMAIL	Email on your X account	Yes
TWITTER_PASSWORD	Your X password	Yes
USER_AGENT	Optional browser UA	No

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

---

Available Tools

Tool	Description
search_twitter	Search tweets by query. sort_by: Top or Latest
get_user_tweets	Get tweets from a user's timeline
get_timeline	Your For You feed
get_latest_timeline	Your Following feed
post_tweet	Post a tweet. Supports media, replies, and @mentions
delete_tweet	Delete a tweet by ID
send_dm	Send a DM to a user. Optional media attachment.
delete_dm	Delete a DM by message ID

---

Rate Limits

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

Endpoint	Limit	Window
Tweets	300 tweets	15 min
DMs	1,000 messages	15 min

---

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