XMCP Server

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