Skip to main content
Glama
TwitGhost

TwitGhost

by arvinmoj

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: Twitter MCP Server

Installation

Prerequisites

  • Python 3.10+

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

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:

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

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


License

MIT

Available Tools

8 tools
delete_dmC

Delete a direct message by its ID.

Inputs: message_id (required). Returns: result

delete_tweetC

Delete a tweet by its ID.

Inputs: tweet_id (required). Returns: result

get_latest_timelineC

Get tweets from your home timeline (Following).

Inputs: count. Returns: result

get_timelineC

Get tweets from your home timeline (For You).

Inputs: count. Returns: result

get_user_tweetsC

Get tweets from a specific user's timeline.

Inputs: username (required), tweet_type, count. Returns: result

post_tweetC

Post a tweet with optional media, reply, and tags.

Inputs: text (required), media_paths, reply_to, tags. Returns: result

search_twitterC

Search twitter with a query. Sort by 'Top' or 'Latest'

Inputs: query (required), sort_by, count. Returns: result

send_dmC

Send a direct message to a user.

Inputs: user_id (required), message (required), media_path. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools are clearly distinct, but get_latest_timeline and get_timeline both retrieve home timeline tweets with only a subtle difference (Following vs For You), which could cause misselection.

    Naming Consistency5/5

    All tools use snake_case with a consistent verb_noun pattern (delete_, get_, post_, search_, send_), making them predictable.

    Tool Count5/5

    8 tools is well-scoped for a Twitter API wrapper, covering posting, deleting, reading, searching, and DMs without being excessive.

    Completeness3/5

    Missing essential operations like get_tweet by ID and list/get DMs, which creates dead ends for common workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to access Twitter/X data including user profiles, tweets, search, and follower events via a set of MCP tools.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with X (Twitter) API v2 for posting tweets, searching, liking, retweeting, and more through natural language.
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to post, search, and manage tweets on X (Twitter) via the MCP protocol.
      10
      2
      -