X (Twitter) MCP Server

io.github.Role1776/mcp-x

Repository Registry

What is the X (Twitter) MCP server?

Search, read and publish X posts and manage users, lists and media via the X API v2.

How to install X (Twitter)

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

X_API_KEY
required
secret
OAuth 1.0a consumer key. developer.x.com -> your project -> your app -> Keys and tokens.
X_API_KEY_SECRET
required
secret
OAuth 1.0a consumer secret, issued together with X_API_KEY.
X_ACCESS_TOKEN
required
secret
User access token. Set the app permissions to Read and Write BEFORE generating it: a token keeps the permissions it was created with, and a read-only one fails every write until it is regenerated.
X_ACCESS_TOKEN_SECRET
required
secret
User access token secret, issued together with X_ACCESS_TOKEN.
MEDIA_ROOT
required
Absolute path to an existing directory - the only one x_media_upload may read files from. Anything outside it is refused, symlinks included. Checked at startup.
MCP_TRANSPORT
stdio (client spawns the process) or http (streamable HTTP listener).
MCP_NAME
Server name reported in the MCP initialize handshake.
MCP_PATH
HTTP path the MCP endpoint is served on. Used only when MCP_TRANSPORT=http.
SERVER_PORT
TCP port to listen on. Used only when MCP_TRANSPORT=http.
SERVER_READ_TIMEOUT
HTTP read timeout as a Go duration. Used only when MCP_TRANSPORT=http.
SERVER_WRITE_TIMEOUT
HTTP write timeout as a Go duration. Used only when MCP_TRANSPORT=http.
LOG_MODE
local (text, debug) or prod (JSON, info). Logs go to stderr.
MAX_IDLE_CONNS_PER_HOST
Idle connections the outbound HTTP client keeps per host.
X_DEBUG
Log the raw requests sent to the X API. Verbose; the output can contain request details, so keep it off outside debugging.
POSTS_MAX_QUERIES
Queries accepted in one x_posts_search or x_posts_count call.
POSTS_MAX_USERNAMES
Usernames accepted in one x_posts_by_user call.
POSTS_MAX_IDS
Post ids accepted in one x_posts_lookup call. The X API caps this at 100.
POSTS_DEFAULT_RESULTS
Posts returned per query when the call does not ask for a count. Every post returned is billed.
POSTS_MAX_RESULTS
Upper bound for posts per query. The X API caps this at 100.
POSTS_DEFAULT_DAYS
How far back post searches look when the call does not say, in days.
POSTS_MAX_DAYS
Furthest back a post search may look, in days. Recent search cannot exceed 7.
POSTS_DEFAULT_TIMEOUT_MS
Timeout for a posts call in milliseconds when the call does not request one.
POSTS_MIN_TIMEOUT_MS
Lowest timeout a posts call may request, in milliseconds.
POSTS_MAX_TIMEOUT_MS
Highest timeout a posts call may request, in milliseconds.
USERS_MAX_USERNAMES
Usernames accepted in one x_users_lookup call. The X API caps this at 100.
USERS_MAX_IDS
User ids accepted in one x_users_lookup call. The X API caps this at 100.
USERS_DEFAULT_RESULTS
Users returned per page when the call does not ask for a count.
USERS_MAX_RESULTS
Upper bound for users per page.
USERS_DEFAULT_TIMEOUT_MS
Timeout for a users call in milliseconds when the call does not request one.
USERS_MIN_TIMEOUT_MS
Lowest timeout a users call may request, in milliseconds.
USERS_MAX_TIMEOUT_MS
Highest timeout a users call may request, in milliseconds.
LISTS_DEFAULT_RESULTS
Items returned per list page when the call does not ask for a count.
LISTS_MAX_RESULTS
Upper bound for items per list page. The X API caps this at 100.
LISTS_DEFAULT_TIMEOUT_MS
Timeout for a lists call in milliseconds when the call does not request one.
LISTS_MIN_TIMEOUT_MS
Lowest timeout a lists call may request, in milliseconds.
LISTS_MAX_TIMEOUT_MS
Highest timeout a lists call may request, in milliseconds.
MEDIA_CHUNK_BYTES
Bytes per upload segment. The X APPEND endpoint caps a segment at 5 MB.
MEDIA_POLL_INTERVAL_MS
How often the upload status is polled while X transcodes a video, in milliseconds.
MEDIA_DEFAULT_TIMEOUT_MS
Timeout for a whole upload in milliseconds when the call does not request one.
MEDIA_MIN_TIMEOUT_MS
Lowest timeout an upload may request, in milliseconds.
MEDIA_MAX_TIMEOUT_MS
Highest timeout an upload may request, in milliseconds.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-x": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/role1776/mcp-x:0.1.1"
      ],
      "env": {
        "X_API_KEY": "<YOUR_X_API_KEY>",
        "X_API_KEY_SECRET": "<YOUR_X_API_KEY_SECRET>",
        "X_ACCESS_TOKEN": "<YOUR_X_ACCESS_TOKEN>",
        "X_ACCESS_TOKEN_SECRET": "<YOUR_X_ACCESS_TOKEN_SECRET>",
        "MEDIA_ROOT": "<YOUR_MEDIA_ROOT>",
        "MCP_TRANSPORT": "<YOUR_MCP_TRANSPORT>",
        "MCP_NAME": "<YOUR_MCP_NAME>",
        "MCP_PATH": "<YOUR_MCP_PATH>",
        "SERVER_PORT": "<YOUR_SERVER_PORT>",
        "SERVER_READ_TIMEOUT": "<YOUR_SERVER_READ_TIMEOUT>",
        "SERVER_WRITE_TIMEOUT": "<YOUR_SERVER_WRITE_TIMEOUT>",
        "LOG_MODE": "<YOUR_LOG_MODE>",
        "MAX_IDLE_CONNS_PER_HOST": "<YOUR_MAX_IDLE_CONNS_PER_HOST>",
        "X_DEBUG": "<YOUR_X_DEBUG>",
        "POSTS_MAX_QUERIES": "<YOUR_POSTS_MAX_QUERIES>",
        "POSTS_MAX_USERNAMES": "<YOUR_POSTS_MAX_USERNAMES>",
        "POSTS_MAX_IDS": "<YOUR_POSTS_MAX_IDS>",
        "POSTS_DEFAULT_RESULTS": "<YOUR_POSTS_DEFAULT_RESULTS>",
        "POSTS_MAX_RESULTS": "<YOUR_POSTS_MAX_RESULTS>",
        "POSTS_DEFAULT_DAYS": "<YOUR_POSTS_DEFAULT_DAYS>",
        "POSTS_MAX_DAYS": "<YOUR_POSTS_MAX_DAYS>",
        "POSTS_DEFAULT_TIMEOUT_MS": "<YOUR_POSTS_DEFAULT_TIMEOUT_MS>",
        "POSTS_MIN_TIMEOUT_MS": "<YOUR_POSTS_MIN_TIMEOUT_MS>",
        "POSTS_MAX_TIMEOUT_MS": "<YOUR_POSTS_MAX_TIMEOUT_MS>",
        "USERS_MAX_USERNAMES": "<YOUR_USERS_MAX_USERNAMES>",
        "USERS_MAX_IDS": "<YOUR_USERS_MAX_IDS>",
        "USERS_DEFAULT_RESULTS": "<YOUR_USERS_DEFAULT_RESULTS>",
        "USERS_MAX_RESULTS": "<YOUR_USERS_MAX_RESULTS>",
        "USERS_DEFAULT_TIMEOUT_MS": "<YOUR_USERS_DEFAULT_TIMEOUT_MS>",
        "USERS_MIN_TIMEOUT_MS": "<YOUR_USERS_MIN_TIMEOUT_MS>",
        "USERS_MAX_TIMEOUT_MS": "<YOUR_USERS_MAX_TIMEOUT_MS>",
        "LISTS_DEFAULT_RESULTS": "<YOUR_LISTS_DEFAULT_RESULTS>",
        "LISTS_MAX_RESULTS": "<YOUR_LISTS_MAX_RESULTS>",
        "LISTS_DEFAULT_TIMEOUT_MS": "<YOUR_LISTS_DEFAULT_TIMEOUT_MS>",
        "LISTS_MIN_TIMEOUT_MS": "<YOUR_LISTS_MIN_TIMEOUT_MS>",
        "LISTS_MAX_TIMEOUT_MS": "<YOUR_LISTS_MAX_TIMEOUT_MS>",
        "MEDIA_CHUNK_BYTES": "<YOUR_MEDIA_CHUNK_BYTES>",
        "MEDIA_POLL_INTERVAL_MS": "<YOUR_MEDIA_POLL_INTERVAL_MS>",
        "MEDIA_DEFAULT_TIMEOUT_MS": "<YOUR_MEDIA_DEFAULT_TIMEOUT_MS>",
        "MEDIA_MIN_TIMEOUT_MS": "<YOUR_MEDIA_MIN_TIMEOUT_MS>",
        "MEDIA_MAX_TIMEOUT_MS": "<YOUR_MEDIA_MAX_TIMEOUT_MS>"
      }
    }
  }
}

Related MCP servers

MCP Retrieval

Active

Local Go MCP server: DuckDuckGo/Bing web + image search, readability scraping to Markdown.

MIT

View repository →

io.github.RoleModel/optics-mcp

Maintained

MCP Server for Optics Design System documentation and token usage.

TypeScript

MIT

View repository →

io.github.RollingGo-AI/hotelbooking

Active

AI-powered hotel search, comparison, and booking for agents and MCP clients—free, unlimited calls, 2M+ hotels worldwide.

Python

MIT

View repository →

io.github.RollingGo-AI/hotelbooking-ai

Active

Search and book 2M+ hotels globally with real-time pricing and inventory via AI agents.

Python

MIT

View repository →

Mails.ai — Agent Email

A real inbox for AI agents: send, receive and thread email, behind a prompt-injection firewall.

Upspring

Maintained

Live ads as reasoning-ready context, plus advertiser spend/traffic/sales scale grades over MCP.

MIT

View repository →