X MCP Server Enhanced Edition

You run an enhanced MCP server for X that supports both OAuth 1.0a and OAuth 2.0, with media uploads, rate limiting, and robust end-to-end tweet operations. This guide shows you how to install, configure, and use the server with an MCP-compatible client, so you can post tweets, upload media, search tweets, and delete tweets from your own X account programmatically.

How to use

Install or connect to the MCP server using an MCP client that supports standard HTTP or stdio-based servers. You can run the server in the background and issue commands through the client to post tweets, search tweets, and manage media. The server automatically handles the appropriate API version for each authentication method and operation, giving you a consistent workflow regardless of whether you choose OAuth 1.0a or OAuth 2.0.

How to install

Prerequisites you need before installing: Node.js 18+ and a working internet connection.

# Install Node.js 18+ from nodejs.org if you don\'t have it

# For installation via Claude Desktop (example configuration shown below)
# 1) Install via MCP in Claude Desktop by configuring an MCP server
# 2) Or install from source and run locally

How to install with Claude Desktop and MCP configuration

You can run the MCP server from Claude Desktop by adding an MCP server entry that uses the npm package directly.

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@mbelinky/x-mcp-server"],
      "env": {
        "API_KEY": "your_api_key_here",
        "API_SECRET_KEY": "your_api_secret_key_here",
        "ACCESS_TOKEN": "your_access_token_here",
        "ACCESS_TOKEN_SECRET": "your_access_token_secret_here"
      }
    }
  }
}

How to install with OAuth 2.0

If you are using OAuth 2.0, set the appropriate environment variables to activate the OAuth 2.0 flow.

{
  "mcpServers": {
    "twitter-mcp": {
      "command": "npx",
      "args": ["-y", "@mbelinky/x-mcp-server"],
      "env": {
        "AUTH_TYPE": "oauth2",
        "OAUTH2_CLIENT_ID": "your_client_id",
        "OAUTH2_CLIENT_SECRET": "your_client_secret",
        "OAUTH2_ACCESS_TOKEN": "your_access_token",
        "OAUTH2_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Additional setup and tooling

If you prefer local development or want to run the server outside Claude, you can install from source and start the server directly using Node.

# From the repository
git clone https://github.com/mbelinky/x-mcp-server.git
cd x-mcp-server/twitter-mcp
npm install
npm run build

# Start locally (example, adjust to your environment)
node dist/index.js

Notes on environment variables and credentials

Use the following environment variables to configure the MCP server for your OAuth method. These are the variables you will place in your MCP config or your shell environment.

# OAuth 1.0a
API_KEY=your_api_key
API_SECRET_KEY=your_api_secret_key
ACCESS_TOKEN=your_access_token
ACCESS_TOKEN_SECRET=your_access_token_secret

# OAuth 2.0 (if using)
AUTH_TYPE=oauth2
OAUTH2_CLIENT_ID=your_client_id
OAUTH2_CLIENT_SECRET=your_client_secret
OAUTH2_ACCESS_TOKEN=your_access_token
OAUTH2_REFRESH_TOKEN=your_refresh_token

Troubleshooting tips

If you encounter authentication or rate limit issues, confirm that your app has the necessary permissions and the tokens include the required scopes. For media uploads, ensure the media.write scope is present for OAuth 2.0.

For debugging, enable verbose logging by setting DEBUG to true in your environment and check the log file in your system logs.

Security and privacy considerations

All credentials are stored locally on your machine. The MCP server is designed to avoid logging sensitive information and to only communicate with Twitter/X APIs. Your tweets, searches, and media remain under your control.

Available actions you can perform with the server

Post tweets with optional media, search tweets with a controllable result count, and delete tweets. The server uses API version handling to apply the most appropriate endpoint based on the authentication method and operation, including a safe fallback path for deletion when v2 has issues.

Available tools

post_tweet

Post a new tweet with optional media attachments and replies.

search_tweets

Search for tweets with a configurable result count.

delete_tweet

Delete a tweet by ID with optional fallback handling for v1.1.

media_upload

Upload media for tweets using the appropriate API version per authentication method.