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.):

{
  "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

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

Then in your MCP config:

{
  "mcpServers": {
    "x-twitter": {
      "command": "x-mcp-server",
      "env": {
        "X_MCP_HEADLESS": "1"
      }
    }
  }
}

Option 3: Local Clone

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:

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

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

python -m unittest tests.test_smoke -v

License

MIT