An MCP (Model Context Protocol) server that gives AI agents full access to the X (Twitter) API. Post tweets, search, read timelines, like, retweet, upload media -- all through natural language.
Works with Claude Code, Claude Desktop, OpenAI Codex, Cursor, Windsurf, Cline, and any other MCP-compatible client.
MCP server for the X (Twitter) API -- give AI agents the ability to post, search, read, and engage on X
If you're an LLM/AI agent helping a user set up this project, read LLMs.md for step-by-step instructions you can walk the user through.
This is a standard stdio MCP server. For any MCP-compatible client, point it at:
node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js
With these environment variables: X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET, X_BEARER_TOKEN.
API Restrictions (as of 2025-2026)
X has progressively restricted what automated/API clients can do. Here's what affects x-mcp:
Likes removed from Free tier (Aug 2025)
The like_tweet endpoint (POST /2/users/:id/likes) was removed from the Free API tier in August 2025. If you're on the Free tier, like_tweet will return a permissions error. Paid tiers (Basic, Pro, Enterprise) are unaffected.
Programmatic replies restricted (Feb 2026)
Replies via the API now only succeed if the original post's author @mentioned you or quoted your post. This applies to all self-serve tiers (Free, Basic, Pro, Pay-Per-Use). Only Enterprise is exempt. Use quote_tweet as a workaround.
Bookmarks require Basic+ tier
Bookmark endpoints have never been available on the Free tier. You need at least Basic ($200/mo) to use get_bookmarks, bookmark_tweet, and unbookmark_tweet.
Your Access Token was generated before you enabled write permissions. Go to the X Developer Portal, ensure App permissions are set to "Read and write", then Regenerate your Access Token and Secret.
401 Unauthorized
Double-check that all 5 credentials in your .env are correct and that there are no extra spaces or line breaks.
429 Rate Limited
The error message includes exactly when the rate limit resets. Wait until then, or reduce request frequency.
Reply fails with a permissions/restriction error
As of Feb 2026, X restricts programmatic replies via the API on all self-serve tiers. You can only reply if the original author @mentions you or quotes your post. This applies to Free, Basic, Pro, and Pay-Per-Use tiers (Enterprise is exempt). Use quote_tweet as a workaround.
Server shows "Connected" but tools aren't used
Make sure you added the server with the correct scope (user/global, not project-scoped if you want it everywhere), then restart your client.
Rate Limiting
Every response includes rate limit info: remaining requests, total limit, and reset time. When a limit is hit, you get a clear error with the exact reset timestamp.
Pagination
List endpoints return a next_token in the response. Pass it back to get the next page of results. Works on: search_tweets, get_timeline, get_mentions, get_followers, get_following.
Search Query Syntax
The search_tweets tool supports X's full query language:
from:username -- posts by a specific user
to:username -- replies to a specific user
#hashtag -- posts containing a hashtag
"exact phrase" -- exact text match
has:media / has:links / has:images -- filter by content type
is:reply / -is:retweet -- filter by post type
lang:en -- filter by language
Combine with spaces (AND) or OR
License
MIT
X
X
Infatoshi·57 ดาว·
MCP server for the X (Twitter) API -- give AI agents the ability to post, search, read, and engage on X