X SocialBLOCK
MCP server for the X (Twitter) API -- give AI agents the ability to post, search, read, and engage on X
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
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.
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.
What Can It Do?
Accepts tweet URLs or IDs interchangeably -- paste https://x.com/user/status/123 or just 123.
Setup
1. Clone and build
git clone https://github.com/INFATOSHI/x-mcp.git cd x-mcp npm install npm run build
2. Get your X API credentials
You need 5 credentials from the X Developer Portal. Here's exactly how to get them:
a) Create an app
- Go to the X Developer Portal
- Sign in with your
f4e8cc087256OBSERVED · 2026-10-08Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add x-mcp --env X_OAUTH2_CLIENT_ID=${X_OAUTH2_CLIENT_ID} --env X_OAUTH2_CLIENT_SECRET=${X_OAUTH2_CLIENT_SECRET} -- npx -y [email protected]{
"mcpServers": {
"x-mcp": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"X_OAUTH2_CLIENT_ID": "${X_OAUTH2_CLIENT_ID}",
"X_OAUTH2_CLIENT_SECRET": "${X_OAUTH2_CLIENT_SECRET}"
}
}
}
}Exposed tools (19)
10 read · 7 write · 2 destructive. Blast radius: 2 tools can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
bookmark_tweet | write | Bookmark a post on X. |
delete_tweet | destructive | Delete a post on X by its ID. |
get_bookmarks | read | Fetch the authenticated user |
get_followers | read | List followers of a user by their numeric user ID. |
get_following | read | List who a user follows by their numeric user ID. |
get_mentions | read | Fetch recent mentions of the authenticated user. |
get_metrics | write | Get engagement metrics for a specific post (impressions, likes, retweets, replies, quotes, bookmarks). Requires the tweet to be authored by the authenticated user for non-public metrics. |
get_timeline | read | Fetch a user |
get_tweet | read | Fetch a tweet and its metadata by ID or URL. Returns author info, metrics, and referenced tweets. |
get_user | read | Look up a user profile by username or user ID. Returns bio, metrics, verification status, etc. |
like_tweet | write | Like a post on X. NOTE: As of Aug 2025, this endpoint was removed from the Free API tier. Only works on paid tiers (Basic, Pro, Enterprise). |
post_tweet | write | Create a new post on X (Twitter). Supports text, polls, and media attachments. |
quote_tweet | write | Quote retweet a post on X. Adds your commentary above the quoted post. |
reply_to_tweet | read | |
retweet | write | Retweet a post on X. |
search_tweets | read | Search recent tweets by query. Supports keywords, hashtags, from:user, to:user, is:reply, has:media, etc. Uses the recent search endpoint (last 7 days). |
setup_oauth2 | read | One-time setup: Authorize OAuth 2.0 for bookmark access. Opens a browser for X login. Required before using get_bookmarks, bookmark_tweet, or unbookmark_tweet. |
unbookmark_tweet | destructive | Remove a bookmark from a post on X. |
upload_media | write | Upload an image or video to X. Returns a media_id that can be attached to posts. Provide the file as base64-encoded data. |
Trust audit
BLOCKgrade D · trust 69/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (1 observation(s))
- Network
- declared (7 observation(s))
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (9)
exec(cmd);
const REDIRECT_URI = "http://127.0.0.1:3219/callback";
const url = new URL(req.url!, `http://127.0.0.1:3219`);
delete_tweet, unbookmark_tweet
@modelcontextprotocol/sdk, dotenv, oauth-1.0a, zod, @types/node, @types/oauth, typescript
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.
3. Save both the **Access Token** and **Access Token Secret**
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
Gates applied: no_behavioural_pass, no_license.
f4e8cc087256full audit observations/trust-audit/mcp-server/infatoshi__x-social.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-08 | f4e8cc087256 | BLOCK | D | 69 | first audit |
Questions
What is the X Social MCP server?
MCP server for the X (Twitter) API -- give AI agents the ability to post, search, read, and engage on X
What tools does X Social expose?
19 in total: 10 read-only, 7 that write, and 2 that can delete or overwrite (delete_tweet, unbookmark_tweet). Every one is listed on this page with its risk.
Is X Social safe to connect to an agent?
No — not without reading the findings first. The audit graded it D (69/100) and found 1 critical or high issue in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 2 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does X Social need?
It reads X_OAUTH2_CLIENT_ID and X_OAUTH2_CLIENT_SECRET from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does X Social run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as x-mcp at 1.0.0.
How current is this page?
The grade is for one exact copy of the source (f4e8cc087256), read on 2026-10-08. The repository is watched and re-audited when it changes.