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

> 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.

Setup: In the X Developer Portal:

1. Create a project and app

2. Enable OAuth 1.0a under "User authentication settings"

3. Set permissions to "Read and Write"

4. 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:

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

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

Setup: In the X Developer Portal:

1. In your app settings, enable OAuth 2.0

2. Set type to "Confidential client" or "Public client"

3. Add a callback URL

4. 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:

Available Tools (26)

Timeline & Search

Post Management

Engagement

Users

Articles

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:

1. 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.

2. 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

1. Fork the repository

2. Create your feature branch (`git checkout -b feature/amazing-feature`)

3. Commit your changes (`git commit -m 'Add some amazing feature'`)

4. Push to the branch (`git push origin feature/amazing-feature`)

5. Open a Pull Request