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:

Profile	Tools	Use Case
researcher	23	Monitoring, analysis, research (read-only)
creator	41	Content creation, audience engagement
manager	55	Full account management
automation	70	Bots, full automation (including DMs)
custom	varies	Pick exactly what you need

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

Tool	Description
search_twitter	Search with full engagement metrics
search_articles	Find tweets containing X articles
get_trends	Worldwide trending topics
get_article	Fetch article content (Playwright)

User & Tweet Info

Tool	Description
get_user_by_screen_name	User by @handle
get_user_profile	User by ID with metrics
get_tweet_details	Full tweet info
get_conversation	Complete thread
get_replies	Replies to a tweet

Engagement

Tool	Description
favorite_tweet	Like
retweet	Retweet
bookmark_tweet	Bookmark
quote_tweet	Quote with comment

Publishing

Tool	Description
post_tweet	Post with media, tags, reply
create_thread	Post multiple tweets as thread
create_poll_tweet	Create a poll

Social

Tool	Description
follow_user / unfollow_user	Follow management
block_user / unblock_user	Block management
mute_user / unmute_user	Mute management

---

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

Variable	Description	Default
X_MCP_PROFILE	Permission profile	researcher
X_MCP_GROUPS	Groups for custom profile	research
X_MCP_DISABLED_TOOLS	Tools to disable	none
X_MCP_ENABLED_TOOLS	Tools to force-enable	none

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:

Action	Limit	Window
Tweets	300	15 min
Likes	1000	24 hours
Follows	400	24 hours
DMs	1000	15 min

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.

Client	Config Location	Status
Claude Desktop	~/.claude.json	Native
Claude Code	CLAUDE.md	Native
Cursor	.cursorrules	Native
Cline	.clinerules	Native
Windsurf	.windsurfrules	Native
Continue.dev	.continue/mcpServers/	Native
OpenClaw	~/.openclaw/skills/	Native
Zed	.zed/settings.json	Native
ChatGPT Desktop	~/.chatgpt/mcp.json	Native
Sourcegraph Cody	OpenCTX	Native
Firebase Genkit	genkitx-mcp plugin	Plugin
Taal	taal.yaml (sync all)	Sync
VS Code + OpenMCP	Extension settings	Plugin
Ollama + Continue	Continue config	Native

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:

File	Editor
.cursorrules	Cursor
.clinerules	Cline
.windsurfrules	Windsurf
CLAUDE.md	Claude Code
LLM_CONTEXT.md	Any LLM (copy to prompt)
docs/AGENT_RULES.md	Comprehensive rules

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

Document	Description
README.md	This file - full documentation
QUICKSTART.md	5-minute setup guide
CLAUDE.md	Instructions for AI agents
LLM_CONTEXT.md	Context block for LLM prompts
docs/AGENT_RULES.md	Rules for all AI editors

---

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