XMCP

The most comprehensive MCP server for X/Twitter with permission-based access control, 70+ tools, and Playwright-powered article fetching.

Highlights

• 70+ tools across research, engagement, publishing, social, lists, DMs
• Permission profiles with runtime enforcement
• Playwright-powered article fetching for X articles
• Full engagement metrics and thread support
• Broad MCP client compatibility

Quick Start

1. Install

pip install "xmcp[articles] @ git+https://github.com/vibeforge1111/xmcp.git"
python -m playwright install chromium

Note: The package name is xmcp and the server command is xmcp-server.

2. Get API Keys (Required)

XMCP requires X/Twitter API credentials to run. If you see errors about missing API keys, follow this quick guide:

1. Go to https://developer.twitter.com and sign in.
2. Create a Project and App (or open an existing one).
3. In the App Keys and Tokens tab, generate:
   • API Key and API Secret
   • Access Token and Access Token Secret
   • Bearer Token
4. Copy .env.example to .env and paste your keys.

Common error messages and fixes:

• "Missing required environment variable" -> add the missing key to .env or your MCP config.
• "403 Forbidden" / "Error 453" -> your X API access tier does not include that endpoint.

Get your credentials from developer.twitter.com:

• API Key & Secret
• Access Token & Secret
• Bearer Token

You can store them in a local .env file:

# Windows (PowerShell)
copy .env.example .env

# macOS/Linux
cp .env.example .env

Do not commit .env. It is ignored by default.

3. Configure

Add to your Claude settings (~/.claude.json):

{
  "mcpServers": {
    "xmcp": {
      "type": "stdio",
      "command": "xmcp-server",
      "env": {
        "TWITTER_API_KEY": "your_key",
        "TWITTER_API_SECRET": "your_secret",
        "TWITTER_ACCESS_TOKEN": "your_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_token_secret",
        "TWITTER_BEARER_TOKEN": "your_bearer",
        "X_MCP_PROFILE": "researcher"
      }
    }
  }
}

If you name the server xmcp, tools will appear as mcp__xmcp__* in clients that show tool prefixes.

4. Use

"Search for tweets about AI"        -> search_twitter
"Read this article: x.com/..."      -> get_article (Playwright)
"Post: Hello world!"                -> post_tweet (requires creator profile)

Permission Profiles

Choose what capabilities to enable:

Setting a Profile

"env": {
  "X_MCP_PROFILE": "creator"
}

Permissions are evaluated at runtime. You can switch profiles or groups without restarting the server.

Custom Profile

"env": {
  "X_MCP_PROFILE": "custom",
  "X_MCP_GROUPS": "research,engage,publish"
}

Tool Groups

research (18 tools) - Read-only, safe

Search, user lookup, tweet details, timelines, trends, article fetching

engage (9 tools) - Low risk

Like, unlike, bookmark, retweet, unretweet

publish (7 tools) - Medium risk

Post tweet, delete, quote, create thread, polls

social (8 tools) - Medium-high risk

Follow, unfollow, block, unblock, mute, unmute

conversations (5 tools) - Safe

Get full threads, replies, quote tweets, hide/unhide replies

lists (14 tools) - Low risk

Create, delete, manage lists and members

dms (3 tools) - High risk

Send and read direct messages

account (1 tool) - High risk

Get authenticated user profile

Key Tools

Search & Discovery

User & Tweet Info

Engagement

Publishing

Social

Human-In-The-Loop Advisory

This MCP is designed to improve research and workflows, not to replace human judgment. Publishing tools return an advisory field that recommends a human review for posts and replies.

Real-Time Use Cases (No Extra Telemetry)

You can drive real-time workflows by polling tools on a schedule from your client or a cron job. Common patterns:

• Trend snapshots every hour using get_trends
• Keyword monitoring using search_twitter
• Article tracking using search_articles + get_article

This keeps the server simple while still enabling real-time visibility.

Article Fetching

X articles require JavaScript to render. This MCP uses Playwright.

# Correct - uses Playwright internally
result = await get_article("https://x.com/user/status/123")
# Returns: {title, author, content, url}

# WRONG - will fail
WebFetch("https://x.com/...")  # Returns empty content

Setup

pip install playwright
python -m playwright install chromium

Configuration Reference

Environment Variables

Credentials are read locally and only used to authenticate requests to X/Twitter.

Examples

Research only (safest):

"X_MCP_PROFILE": "researcher"

Content creator:

"X_MCP_PROFILE": "creator"

Custom - research + likes only:

"X_MCP_PROFILE": "custom",
"X_MCP_GROUPS": "research,engage",
"X_MCP_DISABLED_TOOLS": "retweet,unretweet"

Runtime Permissions

Permissions are evaluated at runtime. This means you can:

• Switch profiles or groups without restarting the server
• Use different profiles per request in HTTP mode

Error Responses

Errors return a consistent envelope:

{
  "ok": false,
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "status": 429,
    "details": {
      "action_type": "tweet_actions",
      "retry_after_seconds": 10
    }
  },
  "tool": "post_tweet",
  "timestamp": "2026-02-03T12:00:00+00:00"
}

Rate Limits

Built-in protection:

Note: These limits are local guardrails, not official Twitter API limits.

Limitations

• get_user_followers_you_know and get_highlights_tweets are simulated with available API data
• vote_on_poll returns not_supported because the API does not support programmatic voting
• Article fetching requires Playwright and a Chromium install

Compatible Clients

Works with all major MCP clients. See COMPATIBILITY.md for full setup guides.

Pre-made Config Files

Ready-to-use configs in configs/ directory:

configs/
|-- continue.yaml              # Continue.dev (YAML)
|-- continue.json              # Continue.dev (JSON)
|-- openclaw-skill.yaml        # OpenClaw skill
|-- zed-settings.json          # Zed editor
|-- chatgpt-mcp.json           # ChatGPT Desktop
|-- taal.yaml                  # Taal cross-client sync
|-- sourcegraph-openctx.json   # Sourcegraph Cody
|-- genkit-plugin.ts           # Firebase Genkit
`-- vscode-openmcp.json        # VS Code OpenMCP

For AI Agents

This package includes rules files for AI code editors:

Key rule: Use get_article for X URLs, not WebFetch.

HTTP Server Mode

For cloud deployments:

xmcp-http  # Runs on port 8081
PORT=8080 xmcp-http  # Custom port

Installation Options

From GitHub (recommended)

pip install "xmcp[articles] @ git+https://github.com/vibeforge1111/xmcp.git"

From PyPI (when published)

pip install xmcp[articles]

From Source

git clone https://github.com/vibeforge1111/xmcp.git
cd xmcp
pip install -e .[articles]
python -m playwright install chromium

Documentation

Credits

Built on the upstream project by Rafal Janicki: https://github.com/rafaljanicki/x-twitter-mcp-server

Update Log

See CHANGELOG.md for a summary of enhancements made in XMCP.

Enhanced by VibeShip with:

• Permission-based access control (5 profiles, 8 groups)
• 70+ tools (vs ~20 original)
• Playwright article fetching
• Thread creation and reading
• Full Lists, DMs, Social actions
• Comprehensive engagement metrics
• AI agent documentation

License

MIT License - see LICENSE