x-mcp-server MCP Server

X MCP Server

A Model Context Protocol (MCP) server for X (Twitter) integration. Provides 26 tools for reading timelines, posting, searching, engagement (likes, retweets, bookmarks), user lookup, follower export, mentions, likes, articles, and lists. Designed for use with Claude desktop and other MCP-compatible clients.

Features

Timeline & Search - Home timeline, search recent posts (7-day window)
Post Management - Create, reply, quote, delete posts with optional media
Engagement - Like/unlike, retweet/undo, bookmark/unbookmark
User Data - Mentions, liked posts, followers, following, blocks, mutes, owned lists, followed lists, and list memberships
User Lookup - Get user profiles and their recent posts
Media Upload - Images (PNG, JPEG, GIF, WEBP) and videos (MP4, MOV, AVI, WEBM, M4V) via v2 upload API
Dual Auth - OAuth 1.0a for post operations, OAuth 2.0 for media upload (v1.1 upload was sunset June 2025)
Rate Limiting - Automatic per-endpoint rate limit tracking with clear error messages
TypeScript - Full type safety, modular file structure

Prerequisites

Node.js >= 18.0.0
X (Twitter) Developer Account
Claude desktop app (or any MCP-compatible client)

X API Access & Pricing

Tier	Cost	Post Reads	Post Writes	Notes
Free	$0	~100/month	~500/month	No likes/follows; media upload requires OAuth 2.0
Basic	$200/month	10,000/month	3,000/month	Search, limited read access
Pro	$5,000/month	1,000,000/month	300,000/month	Full search, filtered stream
Pay-Per-Use	Credit-based	~$0.005/read	Varies	Launched Feb 2026, 2M reads cap

Like and Follow endpoints were removed from the Free tier in August 2025. Follows/Blocks endpoints are Enterprise-only as of 2025.

Installation

git clone https://github.com/DataWhisker/x-mcp-server.git
cd x-mcp-server
npm install
npm run build

Authentication

The server supports two authentication methods. You need at least one configured.

OAuth 1.0a (Required for basic operations)

Works for all post/engagement/search/user operations.

Environment Variable	Description
`TWITTER_API_KEY`	Consumer Key (API Key)
`TWITTER_API_SECRET`	Consumer Secret (API Key Secret)
`TWITTER_ACCESS_TOKEN`	User Access Token
`TWITTER_ACCESS_SECRET`	User Access Token Secret

Setup: In the X Developer Portal:

Create a project and app
Enable OAuth 1.0a under "User authentication settings"
Set permissions to "Read and Write"
Generate Consumer Keys and Access Tokens

OAuth 2.0 (Required for media upload)

The v1.1 media upload endpoint was sunset in June 2025. Media upload now requires OAuth 2.0 via the v2 upload API.

Option A - Direct access token:

Variable	Description
`TWITTER_OAUTH2_ACCESS_TOKEN`	OAuth 2.0 user access token (expires in 2 hours)

Option B - Auto-refresh (recommended for long-running servers):

Variable	Description
`TWITTER_CLIENT_ID`	OAuth 2.0 Client ID
`TWITTER_CLIENT_SECRET`	OAuth 2.0 Client Secret (optional for public clients)
`TWITTER_OAUTH2_REFRESH_TOKEN`	OAuth 2.0 Refresh Token

Tokens are auto-refreshed and persisted to ~/.x-mcp-tokens.json.

Setup: In the X Developer Portal:

In your app settings, enable OAuth 2.0
Set type to "Confidential client" or "Public client"
Add a callback URL
Request scopes: tweet.read, tweet.write, users.read, media.write, offline.access, like.read, like.write, bookmark.read, bookmark.write, follows.read, block.read, mute.read, list.read

Claude Desktop Configuration

Add to %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "x": {
      "command": "node",
      "args": ["C:/path/to/x-mcp-server/build/index.js"],
      "env": {
        "TWITTER_API_KEY": "your-api-key",
        "TWITTER_API_SECRET": "your-api-secret",
        "TWITTER_ACCESS_TOKEN": "your-access-token",
        "TWITTER_ACCESS_SECRET": "your-access-secret",
        "TWITTER_OAUTH2_ACCESS_TOKEN": "your-oauth2-token"
      }
    }
  }
}

Optional Xquik Search Backend

search_tweets can use Xquik while the rest of the server keeps the default X API client. Set:

Variable	Description
`X_MCP_SEARCH_BACKEND=xquik`	Routes only `search_tweets` to Xquik
`XQUIK_API_KEY`	Xquik API key
`XQUIK_API_BASE_URL`	Optional base URL, defaults to `https://xquik.com/api/v1`

Available Tools (26)

Timeline & Search

Tool	Description	Key Parameters
`get_home_timeline`	Get recent posts from home timeline	`limit` (1-100)
`search_tweets`	Search recent posts (7-day window)	`query`, `limit`

Post Management

Tool	Description	Key Parameters
`get_tweet`	Look up a post by ID	`tweet_id`
`create_tweet`	Create a post with optional media	`text`, `image_path?`, `video_path?`
`reply_to_tweet`	Reply to a post with optional media	`tweet_id`, `text`, `image_path?`, `video_path?`
`quote_tweet`	Quote a post with commentary	`tweet_id`, `text`
`delete_tweet`	Delete your post	`tweet_id`

Engagement

Tool	Description	Key Parameters
`like_tweet`	Like a post (Basic+ tier)	`tweet_id`
`unlike_tweet`	Remove a like	`tweet_id`
`retweet`	Repost to your timeline	`tweet_id`
`undo_retweet`	Remove a repost	`tweet_id`
`bookmark_tweet`	Bookmark for later	`tweet_id`
`unbookmark_tweet`	Remove a bookmark	`tweet_id`
`get_bookmarks`	Get your bookmarks	`limit` (1-100)

Users

Tool	Description	Key Parameters
`get_user`	Look up user by username	`username`
`get_user_tweets`	Get a user's recent posts	`username`, `limit`
`get_user_mentions`	Get posts mentioning a user	`username`, `limit`
`get_user_liked_tweets`	Get a user's liked posts	`username`, `limit`
`get_user_followers`	Get a user's followers	`username`, `limit`
`get_user_following`	Get accounts a user follows	`username`, `limit`
`get_blocking_users`	Get users blocked by the authenticated account	`limit`
`get_muting_users`	Get users muted by the authenticated account	`limit`
`get_owned_lists`	Get lists owned by a user	`username`, `limit`
`get_followed_lists`	Get lists followed by a user	`username`, `limit`
`get_list_memberships`	Get lists a user belongs to	`username`, `limit`

Articles

Tool	Description	Key Parameters
`get_article`	Fetch the full body content of an X Article post	`tweet_id`

Media Support

Images: PNG, JPEG, GIF, WEBP (max 5MB)
Videos: MP4, MOV, AVI, WEBM, M4V (max 512MB, streamed chunked upload)
Cannot attach both image and video to the same post
Requires OAuth 2.0 credentials (v1.1 upload sunset June 2025)
Path restriction: Only files within your home directory or system temp directory can be uploaded (prevents path traversal)

Security

Input validation: Tweet IDs must be numeric (1-20 digits), usernames must match [A-Za-z0-9_]{1,15}
Media path restriction: Upload paths are validated against an allow-list (home directory, temp directory)
Token storage: OAuth 2.0 tokens persisted to ~/.x-mcp-tokens.json with 0o600 permissions (Unix). On Windows, file permissions are not enforced by the OS - protect the file via NTFS ACLs or use environment variables instead.
Error sanitization: X API error details are logged server-side only; sanitized messages are returned to MCP clients
Refresh mutex: Concurrent token refresh attempts are deduplicated to prevent race conditions

Development

npm run build    # Compile TypeScript
npm run dev      # Watch mode
npm start        # Run the server

Project Structure

src/
  index.ts              # MCP server entry point & handler dispatch
  client.ts             # Twitter client setup (OAuth 1.0a + OAuth 2.0)
  media.ts              # v2 media upload (simple + chunked)
  rate-limit.ts         # Per-endpoint rate limiting
  tools/
    definitions.ts      # All 16 tool schemas
    handlers.ts         # Tool handler implementations

Pairing with GetXAPI for Cheaper Read Operations (Optional)

For users who need a cheaper or higher-rate-limit option for read-only Twitter (X) operations such as tweet search, profile lookup, and follower lists, this project can be paired with GetXAPI, a budget Twitter / X data API priced at $0.05 per 1K tweets versus the official X API basic tier at $200 / month.

Two integration patterns:

Run side-by-side in your AI client. Keep this project for its primary workflow and add the official GetXAPI MCP server for read-heavy tasks. Each tool name routes to the backend best suited for that operation.
Add a backend toggle. For a code-level reference of an optional alternative backend behind a single env variable, see the PR pattern merged into a sibling project.

GetXAPI quick start:

Signup with $0.50 free credit (no card required): https://getxapi.com/signup
Official GetXAPI MCP server: https://github.com/getxapi/getxapi-mcp
npm: @getxapi/mcp
Pay-per-call pricing: $0.001 / call, $0.05 / 1K tweets

This pairing is fully optional. No behavior change for existing users.

License

MIT

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

X MCP Server

Features

Timeline & Search - Home timeline, search recent posts (7-day window)
Post Management - Create, reply, quote, delete posts with optional media
Engagement - Like/unlike, retweet/undo, bookmark/unbookmark
User Data - Mentions, liked posts, followers, following, blocks, mutes, owned lists, followed lists, and list memberships
User Lookup - Get user profiles and their recent posts
Media Upload - Images (PNG, JPEG, GIF, WEBP) and videos (MP4, MOV, AVI, WEBM, M4V) via v2 upload API
Dual Auth - OAuth 1.0a for post operations, OAuth 2.0 for media upload (v1.1 upload was sunset June 2025)
Rate Limiting - Automatic per-endpoint rate limit tracking with clear error messages
TypeScript - Full type safety, modular file structure

Prerequisites

Node.js >= 18.0.0
X (Twitter) Developer Account
Claude desktop app (or any MCP-compatible client)

X API Access & Pricing

Tier	Cost	Post Reads	Post Writes	Notes
Free	$0	~100/month	~500/month	No likes/follows; media upload requires OAuth 2.0
Basic	$200/month	10,000/month	3,000/month	Search, limited read access
Pro	$5,000/month	1,000,000/month	300,000/month	Full search, filtered stream
Pay-Per-Use	Credit-based	~$0.005/read	Varies	Launched Feb 2026, 2M reads cap

Like and Follow endpoints were removed from the Free tier in August 2025. Follows/Blocks endpoints are Enterprise-only as of 2025.

Installation

git clone https://github.com/DataWhisker/x-mcp-server.git
cd x-mcp-server
npm install
npm run build

Authentication

The server supports two authentication methods. You need at least one configured.

OAuth 1.0a (Required for basic operations)

Works for all post/engagement/search/user operations.

Environment Variable	Description
`TWITTER_API_KEY`	Consumer Key (API Key)
`TWITTER_API_SECRET`	Consumer Secret (API Key Secret)
`TWITTER_ACCESS_TOKEN`	User Access Token
`TWITTER_ACCESS_SECRET`	User Access Token Secret

Setup: In the X Developer Portal:

Create a project and app
Enable OAuth 1.0a under "User authentication settings"
Set permissions to "Read and Write"
Generate Consumer Keys and Access Tokens

OAuth 2.0 (Required for media upload)

The v1.1 media upload endpoint was sunset in June 2025. Media upload now requires OAuth 2.0 via the v2 upload API.

Option A - Direct access token:

Variable	Description
`TWITTER_OAUTH2_ACCESS_TOKEN`	OAuth 2.0 user access token (expires in 2 hours)

Option B - Auto-refresh (recommended for long-running servers):

Variable	Description
`TWITTER_CLIENT_ID`	OAuth 2.0 Client ID
`TWITTER_CLIENT_SECRET`	OAuth 2.0 Client Secret (optional for public clients)
`TWITTER_OAUTH2_REFRESH_TOKEN`	OAuth 2.0 Refresh Token

Tokens are auto-refreshed and persisted to ~/.x-mcp-tokens.json.

Setup: In the X Developer Portal:

In your app settings, enable OAuth 2.0
Set type to "Confidential client" or "Public client"
Add a callback URL
Request scopes: tweet.read, tweet.write, users.read, media.write, offline.access, like.read, like.write, bookmark.read, bookmark.write, follows.read, block.read, mute.read, list.read

Claude Desktop Configuration

Add to %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "x": {
      "command": "node",
      "args": ["C:/path/to/x-mcp-server/build/index.js"],
      "env": {
        "TWITTER_API_KEY": "your-api-key",
        "TWITTER_API_SECRET": "your-api-secret",
        "TWITTER_ACCESS_TOKEN": "your-access-token",
        "TWITTER_ACCESS_SECRET": "your-access-secret",
        "TWITTER_OAUTH2_ACCESS_TOKEN": "your-oauth2-token"
      }
    }
  }
}

Optional Xquik Search Backend

search_tweets can use Xquik while the rest of the server keeps the default X API client. Set:

Variable	Description
`X_MCP_SEARCH_BACKEND=xquik`	Routes only `search_tweets` to Xquik
`XQUIK_API_KEY`	Xquik API key
`XQUIK_API_BASE_URL`	Optional base URL, defaults to `https://xquik.com/api/v1`

Available Tools (26)

Timeline & Search

Tool	Description	Key Parameters
`get_home_timeline`	Get recent posts from home timeline	`limit` (1-100)
`search_tweets`	Search recent posts (7-day window)	`query`, `limit`

Post Management

Tool	Description	Key Parameters
`get_tweet`	Look up a post by ID	`tweet_id`
`create_tweet`	Create a post with optional media	`text`, `image_path?`, `video_path?`
`reply_to_tweet`	Reply to a post with optional media	`tweet_id`, `text`, `image_path?`, `video_path?`
`quote_tweet`	Quote a post with commentary	`tweet_id`, `text`
`delete_tweet`	Delete your post	`tweet_id`

Engagement

Tool	Description	Key Parameters
`like_tweet`	Like a post (Basic+ tier)	`tweet_id`
`unlike_tweet`	Remove a like	`tweet_id`
`retweet`	Repost to your timeline	`tweet_id`
`undo_retweet`	Remove a repost	`tweet_id`
`bookmark_tweet`	Bookmark for later	`tweet_id`
`unbookmark_tweet`	Remove a bookmark	`tweet_id`
`get_bookmarks`	Get your bookmarks	`limit` (1-100)

Users

Tool	Description	Key Parameters
`get_user`	Look up user by username	`username`
`get_user_tweets`	Get a user's recent posts	`username`, `limit`
`get_user_mentions`	Get posts mentioning a user	`username`, `limit`
`get_user_liked_tweets`	Get a user's liked posts	`username`, `limit`
`get_user_followers`	Get a user's followers	`username`, `limit`
`get_user_following`	Get accounts a user follows	`username`, `limit`
`get_blocking_users`	Get users blocked by the authenticated account	`limit`
`get_muting_users`	Get users muted by the authenticated account	`limit`
`get_owned_lists`	Get lists owned by a user	`username`, `limit`
`get_followed_lists`	Get lists followed by a user	`username`, `limit`
`get_list_memberships`	Get lists a user belongs to	`username`, `limit`

Articles

Tool	Description	Key Parameters
`get_article`	Fetch the full body content of an X Article post	`tweet_id`

Media Support

Images: PNG, JPEG, GIF, WEBP (max 5MB)
Videos: MP4, MOV, AVI, WEBM, M4V (max 512MB, streamed chunked upload)
Cannot attach both image and video to the same post
Requires OAuth 2.0 credentials (v1.1 upload sunset June 2025)
Path restriction: Only files within your home directory or system temp directory can be uploaded (prevents path traversal)

Security

Input validation: Tweet IDs must be numeric (1-20 digits), usernames must match [A-Za-z0-9_]{1,15}
Media path restriction: Upload paths are validated against an allow-list (home directory, temp directory)
Token storage: OAuth 2.0 tokens persisted to ~/.x-mcp-tokens.json with 0o600 permissions (Unix). On Windows, file permissions are not enforced by the OS - protect the file via NTFS ACLs or use environment variables instead.
Error sanitization: X API error details are logged server-side only; sanitized messages are returned to MCP clients
Refresh mutex: Concurrent token refresh attempts are deduplicated to prevent race conditions

Development

npm run build    # Compile TypeScript
npm run dev      # Watch mode
npm start        # Run the server

Project Structure

src/
  index.ts              # MCP server entry point & handler dispatch
  client.ts             # Twitter client setup (OAuth 1.0a + OAuth 2.0)
  media.ts              # v2 media upload (simple + chunked)
  rate-limit.ts         # Per-endpoint rate limiting
  tools/
    definitions.ts      # All 16 tool schemas
    handlers.ts         # Tool handler implementations

Pairing with GetXAPI for Cheaper Read Operations (Optional)

Two integration patterns:

Run side-by-side in your AI client. Keep this project for its primary workflow and add the official GetXAPI MCP server for read-heavy tasks. Each tool name routes to the backend best suited for that operation.
Add a backend toggle. For a code-level reference of an optional alternative backend behind a single env variable, see the PR pattern merged into a sibling project.

GetXAPI quick start:

Signup with $0.50 free credit (no card required): https://getxapi.com/signup
Official GetXAPI MCP server: https://github.com/getxapi/getxapi-mcp
npm: @getxapi/mcp
Pay-per-call pricing: $0.001 / call, $0.05 / 1K tweets

This pairing is fully optional. No behavior change for existing users.

License

MIT

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

X MCP Server

README Documentation

X MCP Server

Features

Prerequisites

X API Access & Pricing

Installation

Authentication

OAuth 1.0a (Required for basic operations)

OAuth 2.0 (Required for media upload)

Claude Desktop Configuration

Optional Xquik Search Backend

Available Tools (26)

Timeline & Search

Post Management

Engagement

Users

Articles

Media Support

Security

Development

Project Structure

Pairing with GetXAPI for Cheaper Read Operations (Optional)

License

Contributing

Quick Install

Quick Actions

Key Features

X MCP Server

README Documentation

X MCP Server

Features

Prerequisites

X API Access & Pricing

Installation

Authentication

OAuth 1.0a (Required for basic operations)

OAuth 2.0 (Required for media upload)

Claude Desktop Configuration

Optional Xquik Search Backend

Available Tools (26)

Timeline & Search

Post Management

Engagement

Users

Articles

Media Support

Security

Development

Project Structure

Pairing with GetXAPI for Cheaper Read Operations (Optional)

License

Contributing

Quick Install

Quick Actions

Key Features