# TwitGhost

[![smithery badge](https://smithery.ai/badge/mcp-twitghost)](https://smithery.ai/server/mcp-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`](https://github.com/adhikasp/mcp-twikit) that uses the [`unclecode/twikit`](https://github.com/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)

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

### Manual (uvx)

```json
{
  "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)

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

Then configure in your MCP client:

```json
{
  "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:

```bash
pip show twikit
# Source should show unclecode/twikit
```

If it still shows `d60/twikit`, reinstall:

```bash
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:

```bash
pip install --upgrade certifi
```

---

## Credits

- Based on [`adhikasp/mcp-twikit`](https://github.com/adhikasp/mcp-twikit) — original MCP Twitter server
- Uses [`unclecode/twikit`](https://github.com/unclecode/twikit) fork for X API compatibility
- Built with [FastMCP](https://github.com/jlowin/fastmcp) and the MCP protocol

---

## License

MIT