mcp-server-x

An MCP (Model Context Protocol) server for X (Twitter). Built in Rust using OAuth 1.0a and the X API v2. Supports multiple accounts.

Communicates via stdio using JSON-RPC 2.0.

Tools

All tools accept an optional `account` parameter to select which X account to use. Omit it to use the default account.

Quick Start

1. Build

cargo build --release

Produces `target/release/mcp-server-x` (optimized with LTO, stripped).

2. Configure credentials

The server looks for the config at the first existing of:

• `$XDG_CONFIG_HOME/mcp-server-x/config.toml`
• `~/.config/mcp-server-x/config.toml`
• `$XDG_CONFIG_HOME/mcp-server-post-x/config.toml` (legacy)
• `~/.config/mcp-server-post-x/config.toml` (legacy)

You can also run without any config file by providing credentials via environment variables (great for containers/CI):

export X_API_KEY=...
export X_API_KEY_SECRET=...
export X_ACCESS_TOKEN=...
export X_ACCESS_TOKEN_SECRET=...
# Optional:
# export X_ACCOUNT_NAME=myaccount

`POST_X_*` / `POST_X_ACCOUNT_NAME` are still accepted if the `X_*` vars are unset.

Create the config file (classic approach):

mkdir -p ~/.config/mcp-server-x

Create `~/.config/mcp-server-x/config.toml`:

Single account (no `default_account` needed):

[accounts.myaccount]
api_key = "your-api-key"
api_key_secret = "your-api-key-secret"
access_token = "your-access-token"
access_token_secret = "your-access-token-secret"

Multiple accounts:

default_account = "myaccount"

[accounts.myaccount]
api_key = "your-api-key"
api_key_secret = "your-api-key-secret"
access_token = "your-access-token"
access_token_secret = "your-access-token-secret"

[accounts.otheraccount]
api_key = "your-api-key"
api_key_secret = "your-api-key-secret"
access_token = "other-access-token"
access_token_secret = "other-access-token-secret"

Notes:

• Account keys are X usernames (e.g. `[accounts.codechap]`)
• If you have multiple accounts, `default_account` is required
• If you have one account, `default_account` is optional (auto-detected)
• Multiple accounts can share the same `api_key`/`api_key_secret` (same X app). Only the `access_token`/`access_token_secret` differ per account.
• `bookmark_tweet` / `unbookmark_tweet` require OAuth 2.0 User Context (`bookmark.write`). Add optional `oauth2_client_id`, `oauth2_client_secret`, `oauth2_access_token`, and `oauth2_refresh_token` on the account that needs bookmarks. OAuth 1.0a stays in use for every other tool. Generate the user token in the X Developer Console (App → Keys & Tokens → OAuth 2.0 Access Token) with `tweet.read`, `users.read`, `bookmark.read`, `bookmark.write`, and `offline.access`. Access tokens last ~2 hours; the server refreshes them with `oauth2_refresh_token` (and writes the rotated tokens back to `config.toml`).

Secure it:

chmod 700 ~/.config/mcp-server-x
chmod 600 ~/.config/mcp-server-x/config.toml

See Getting credentials below for how to obtain these.

3. Add to your MCP client

Claude Code (`~/.claude.json`):

{
  "mcpServers": {
    "x": {
      "command": "/path/to/mcp-server-x"
    }
  }
}

Then ask Claude things like:

• "Post a tweet saying hello world"
• "Post a tweet as securechap saying hello world"
• "Search for tweets about Rust"
• "Show me my timeline"
• "Like this tweet: https://x.com/someone/status/123456"
• "Who are my followers?"
• "Look up @elonmusk"
• "List my accounts"

Tool Reference

list_accounts

No required parameters. Returns available account names, which is the default, and cached usernames.

post_tweet

post_thread

delete_tweet / like_tweet / unlike_tweet / retweet / unretweet / bookmark_tweet / unbookmark_tweet

All accept URLs like `https://x.com/user/status/123456` — the ID is extracted automatically.

upload_media

Returns a `media_id` to use with `post_tweet`'s `media_ids` param.

update_profile

Update the authenticated user's profile text fields. At least one field must be provided; only the fields you pass are changed, and passing an empty string clears that field.

\* At least one of `description`, `name`, `location`, or `url` is required.

Uses the legacy `POST /1.1/account/update_profile.json` endpoint (no v2 equivalent). Requires the app to have Read and Write permission; without it the endpoint returns 403.

update_profile_banner

Uses the legacy `POST /1.1/account/update_profile_banner.json` endpoint (base64 `banner` param; no v2 equivalent). Success returns HTTP 200 with no body.

search_tweets

get_trends

Returns trend names and approximate post volumes.

get_timeline

get_bookmarks

lookup_user / follow_user / unfollow_user

get_followers / get_following

get_all_followers / get_all_following

Auto-paginates through results (100 per page) with a 200ms delay between pages. For accounts with tens of thousands of followers, prefer the paginated `get_followers` / `get_following` tools instead.

get_dm_events

send_dm

get_me

Returns your user ID, display name, and @username.

Adding Additional Accounts

To add another X account to an existing app (without a separate developer account), use the included OAuth authorization script:

export X_API_KEY="your-app-api-key"
export X_API_KEY_SECRET="your-app-api-key-secret"
./oauth-authorize.sh

Important: The script no longer contains any hardcoded credentials. You must provide your own app's Consumer Keys via the two environment variables shown above.

This runs the 3-legged OAuth 1.0a PIN-based flow:

1. Opens a URL where the new account authorizes your app

2. You paste the PIN back into the terminal

3. It outputs the `[accounts.username]` config block to add to your `config.toml`

All accounts you authorize share the same X App (and its rate limits + billing). This is the normal pattern for multi-account usage.

Getting Credentials

1. Go to developer.x.com and sign up for a developer account

2. Create a Project and an App in the Developer Console

3. In your App settings, set up User authentication:

4. Go to Keys and tokens and generate:

5. Copy all four values into your `config.toml` under `[accounts.yourusername]`

The server validates credentials at startup. If you get persistent 401 errors, regenerate your tokens at developer.x.com.

Development

cargo build              # debug build
cargo run                # run in dev mode
RUST_LOG=debug cargo run # debug logging (credentials are redacted)

cargo test               # run unit tests
cargo clippy -- -D warnings   # strict lint check (must pass)
cargo build --release    # optimized binary

Technical Details

• Auth: OAuth 1.0a with HMAC-SHA1 signatures (RFC 5849, RFC 3986 percent-encoding)
• Multi-account: Multiple X accounts per server instance, selectable per tool call
• Tweet API: X API v2 (`api.x.com/2/`)
• Media upload: v1.1 chunked upload (`upload.twitter.com/1.1/media/upload.json`) — INIT/APPEND/FINALIZE/STATUS flow for video/GIF, simple multipart for images
• Media limits: JPEG/PNG/WebP up to 5MB, GIF up to 15MB, MP4 up to 512MB
• Media validation: Max 4 images OR 1 video OR 1 GIF per tweet (no mixing)
• Thread posting: 500ms delay between tweets, chained via `in_reply_to_tweet_id`
• Retry logic: Automatic retry with exponential backoff on 503 errors
• Rate limits: 429 responses include reset timestamp in error message (no auto-retry — the caller decides)
• Safety: `get_all_followers` / `get_all_following` are capped at 10k users by default to avoid destroying LLM context windows
• Rust edition: 2021 (broad compatibility)

Project Structure

src/
  main.rs    — entry point, config loading, tracing, stdio transport
  server.rs  — MCP tool handlers, response formatting, multi-account routing
  api.rs     — X API client: OAuth signing, tweet/media/user/DM endpoints
  params.rs  — tool parameter types (serde + JSON Schema)