X MCP Server

x-mcp

An MCP (Model Context Protocol) server that gives AI agents full access to the X (Twitter) API. Post tweets, search, read timelines, like, retweet, upload media -- all through natural language.

Works with Claude Code, Claude Desktop, OpenAI Codex, Cursor, Windsurf, Cline, and any other MCP-compatible client.

If you're an LLM/AI agent helping a user set up this project, read `LLMs.md` for step-by-step instructions you can walk the user through.

What Can It Do?

Accepts tweet URLs or IDs interchangeably -- paste https://x.com/user/status/123 or just 123.

Setup

1. Clone and build

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

2. Get your X API credentials

You need 5 credentials from the X Developer Portal. Here's exactly how to get them:

a) Create an app

1. Go to the X Developer Portal
2. Sign in with your X account
3. Go to Apps in the left sidebar
4. Click Create App (you may need to sign up for a developer account first)
5. Give it a name (e.g., my-x-mcp)
6. You'll immediately see your Consumer Key (API Key), Secret Key (API Secret), and Bearer Token
7. Save all three now -- the secret won't be shown again

b) Enable write permissions

By default, new apps only have Read permissions. You need Read and Write to post tweets, like, retweet, etc.

1. In your app's page, scroll down to User authentication settings
2. Click Set up
3. Set App permissions to Read and write
4. Set Type of App to Web App, Automated App or Bot
5. Set Callback URI / Redirect URL to https://localhost (required but won't be used)
6. Set Website URL to any valid URL (e.g., https://x.com)
7. Click Save

c) Generate access tokens (with write permissions)

After enabling write permissions, you need to generate (or regenerate) your Access Token and Secret so they carry the new permissions:

1. Go back to your app's Keys and Tokens page
2. Under Access Token and Secret, click Regenerate
3. Save both the Access Token and Access Token Secret

If you skip step (b) before generating tokens, your tokens will be Read-only and posting will fail with a 403 error.

3. Configure credentials

Copy the example env file and fill in your 5 credentials:

cp .env.example .env

Edit .env:

X_API_KEY=your_consumer_key
X_API_SECRET=your_secret_key
X_BEARER_TOKEN=your_bearer_token
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret

Connect to Your Client

Pick your client below. You only need to follow one section.

Claude Code

claude mcp add --scope user x-twitter -- node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

Replace /ABSOLUTE/PATH/TO/x-mcp with the actual path where you cloned the repo. Then restart Claude Code.

Claude Desktop

Add to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

Cursor

Add to your Cursor MCP config:

• Global (all projects): ~/.cursor/mcp.json
• Project-scoped: .cursor/mcp.json in your project root

{
  "mcpServers": {
    "x-twitter": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"],
      "env": {
        "X_API_KEY": "your_consumer_key",
        "X_API_SECRET": "your_secret_key",
        "X_ACCESS_TOKEN": "your_access_token",
        "X_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "X_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

You can also verify the connection in Cursor Settings > MCP Servers.

Ope