# x-mcp-playwright v1.3.0

Stealth Twitter/X MCP server powered by Patchright (stealth Playwright fork), persistent multi-profile sessions, WebRTC leak protection, and humanized keystroke dynamics.

9 grouped tools - 33 actions preserved, zero functionality lost.

## Features

- **Stealth & Anti-Detection**: Patchright engine with WebRTC leak prevention, randomized keystroke intervals (`human_type`), and browser fingerprint masking.
- **Proxy Support (HTTP/HTTPS/SOCKS5)**: Route all traffic through custom proxies or `ssh-mcp` SOCKS5 tunnels (`X_MCP_PROXY="socks5://127.0.0.1:1080"`).
- **Fast Media Route Blocking**: Automatically aborts images, heavy media, fonts, and telemetry during search and scraping operations for up to 3x speedup and 75% RAM reduction.
- **Multi-Profile Session Management**: Easily switch between accounts via `X_MCP_PROFILE="account_name"`.
- **9 Grouped Tools**: Posting, engagement, search, feed browsing, tweet analytics, DMs, list management, session status.

## Installation

### Option 1: Instant via `uvx` (Recommended)

Add directly to your MCP client configuration (`claude_desktop_config.json`, `opencode.json`, etc.):

```json
{
  "mcpServers": {
    "x-twitter": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Steph-ux/x-mcp-playwright.git", "x-mcp-server"],
      "env": {
        "X_MCP_HEADLESS": "1"
      }
    }
  }
}
```

### Option 2: Via `pip install`

```bash
pip install git+https://github.com/Steph-ux/x-mcp-playwright.git
patchright install chromium
```

Then in your MCP config:
```json
{
  "mcpServers": {
    "x-twitter": {
      "command": "x-mcp-server",
      "env": {
        "X_MCP_HEADLESS": "1"
      }
    }
  }
}
```

### Option 3: Local Clone

```bash
git clone https://github.com/Steph-ux/x-mcp-playwright.git
cd x-mcp-playwright
pip install -e .
patchright install chromium
```

### One-Time Interactive Login

To authenticate your session:

```bash
x-mcp-login [optional_profile_name]
# or: python login.py [optional_profile_name]
```

This opens a browser window. Log into your X/Twitter account (complete 2FA if enabled). Once you reach `x.com/home`, the session is automatically saved to `~/.x-mcp-playwright/profiles/<profile_name>/`.

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `X_MCP_HEADLESS` | `1` | `0` to display browser window, `1` for headless mode |
| `X_MCP_PROFILE` | `default` | Name of the active profile directory |
| `X_MCP_PROXY` | `None` | Proxy URL (ex: `socks5://127.0.0.1:1080` or `http://user:pass@host:port`) |
| `X_MCP_TIMEOUT_MS` | `20000` | Default page navigation timeout in milliseconds |
| `X_MCP_SCREENSHOT_DIR` | `~/.x-mcp-playwright/screenshots` | Debug screenshot directory |
| `X_MCP_USE_SYSTEM_CHROME` | `0` | `1` to use system Chrome binary instead of bundled Chromium |

## Tool Catalog (9 Tools, 33 Actions)

### 1. `x_post` - Publish Tweets & Threads (6 Actions)
- `post`: Post single tweet (`text`)
- `thread`: Post connected thread (`tweets` list)
- `post_media`: Post with images/video (`text`, `media_paths`)
- `reply`: Reply to tweet (`tweet_url`, `reply_text`)
- `quote`: Quote tweet (`tweet_url`, `comment`)
- `delete`: Delete own tweet (`tweet_url`)

### 2. `x_engage` - Interact with Tweets (4 Actions)
- `like`: Like/unlike (`tweet_url`, `on=True|False`)
- `retweet`: RT/un-RT (`tweet_url`, `on=True|False`)
- `bookmark`: Save/remove bookmark (`tweet_url`, `on=True|False`)
- `pin`: Pin/unpin (`tweet_url`, `on=True|False`)

### 3. `x_user` - User & Profile Operations (6 Actions)
- `profile`: Fetch user bio and stats (`handle`)
- `timeline`: Fetch user tweets (`handle`, `tab="tweets"|"likes"|"media"`, `limit`)
- `connections`: Fetch followers/following (`handle`, `kind="followers"|"following"`, `limit`)
- `follow`: Follow/unfollow user (`handle`, `on=True|False`)
- `block`: Block user (`handle`)
- `mute`: Mute user (`handle`)

### 4. `x_search` - Simple & Advanced Search
- Search query with filters (`query`, `filter="top"|"latest"|"people"|"media"`, `from_user`, `to_user`, `since`, `until`, `min_likes`, `min_retweets`, `lang`, `limit`)

### 5. `x_feed` - Browse Timelines & Notifications (4 Actions)
- `home`: Home timeline (`tab="for_you"|"following"`, `limit`)
- `bookmarks`: Saved bookmarks (`limit`)
- `notifications`: Mentions, likes, follows (`limit`)
- `trending`: Current trends (`limit`)

### 6. `x_tweet` - Tweet Details & Metrics (4 Actions)
- `details`: Full tweet metrics and text (`tweet_url`)
- `replies`: Thread replies under tweet (`tweet_url`, `limit`)
- `analytics`: Impressions & engagement data for own tweets (`tweet_url`)
- `engagers`: Who liked or retweeted (`tweet_url`, `kind="likes"|"retweets"`)

### 7. `x_list` - List Operations
- User lists and list feeds (`list_id`, `handle`, `limit`)

### 8. `x_dm` - Direct Messages (3 Actions)
- `send`: Send direct message with human keystrokes (`handle`, `message`)
- `conversations`: List active DM conversations (`limit`)
- `messages`: Read conversation messages (`handle`, `limit`)

### 9. `x_session` - Session & Diagnostic Operations
- `check`: Validate login status and active account handle
- `screenshot`: Capture debug screenshot of any page (`url`, `full_page`)

## Testing

```bash
python -m unittest tests.test_smoke -v
```

## License

MIT