x-mcp MCP Server: Full-featured X (Twitter) API Integration & NLP Control for AI Agents

X MCP

An MCP server that provides AI agents with full access to the X (Twitter) API, supporting operations such as posting, searching, interacting, and media uploading, which can be controlled through natural language instructions.

Social media Developer tools #Social media #API integration #AI agents #Automation tools .TypeScript

rating : 2.5 points

downloads : 0

update time : 2026-03-12

Open Site

What is x-mcp?

x-mcp is a Model Context Protocol (MCP) server that encapsulates the full API functionality of X (Twitter) into natural language tools that AI assistants can understand. You no longer need to remember complex API commands or use specialized clients. Simply tell the AI assistant what you want to do on X as if you were talking to a person.

How to use x-mcp?

First, obtain X developer API credentials, then configure the MCP client (such as Claude Desktop, Cursor, etc.) to connect to the x-mcp server. After the configuration is complete, you can directly let the AI assistant manage your X account through conversations.

Applicable scenarios

Suitable for content creators, social media managers, developers, and any users who want to simplify X account operations through AI assistants. Whether it's posting daily tweets, monitoring topics, analyzing data, or managing content in batches, x-mcp can make these tasks easier.

Main features

Post tweets

Post new tweets, reply to existing tweets, quote tweets, or delete tweets. Supports plain text and content with media.

Read content

Get details of a single tweet, search for tweets, view user timelines, and get mention messages. Supports advanced search syntax.

User management

Find user information, view the follower list, and view the following list. Supports paginated retrieval of the full list.

Interaction features

Like tweets and retweet content. Supports direct operations through tweet URLs or IDs.

Media upload

Upload media files such as pictures and attach them when posting tweets.

Data analysis

Get performance data of tweets, such as analysis indicators like the number of views and interactions.

Advantages

Natural language interaction: No need to learn API syntax, describe requirements in daily language

Multi-client support: Compatible with mainstream AI development tools such as Claude, Cursor, and Windsurf

Full function coverage: Supports most core functions of the X API

Intelligent parsing: Automatically identifies tweet URLs or IDs without manual extraction

Real-time feedback: Displays the API rate limit status for each operation

Limitations

Requires an X developer account: Must apply for API credentials, and free accounts have rate limits

Reply limitations: Due to X API policies, the programmatic reply function is restricted (must be mentioned or quoted)

Multiple configuration steps: Need to configure both the server and the client

Depends on network connection: All operations need to be performed through the X API

How to use

Get the project and install

Clone the GitHub repository and install the dependency packages

Apply for X API credentials

Go to the X developer portal to create an application and obtain 5 necessary API keys and tokens

Configure environment variables

Copy the example configuration file and fill in your API credentials

Connect to the MCP client

Add the x-mcp server configuration according to the client you are using (Claude, Cursor, etc.)

Usage examples

Publish a technical sharing

As a developer, you want to share your learning experience about MCP technology

Monitor industry trends

Marketing personnel need to track the latest trends of competitors

Content interaction management

Social media managers need to handle user interactions

Data analysis report

Content creators want to know the performance of their tweets

Frequently Asked Questions

Why do I get a 403 permission error when posting a tweet?

Which MCP clients are supported?

Is there a limit to the tweet reply function?

How do I get the tweet ID?

What should I do if I encounter a rate limit?

What advanced syntax does the search support?

Related resources

GitHub repository

Source code and latest version of x-mcp

X developer portal

Official platform for applying for API credentials

MCP official documentation

Official instructions and specifications of the Model Context Protocol

Claude Desktop configuration guide

How to configure Claude Desktop to use the MCP server

🚀 x-mcp

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

It 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 for step-by-step instructions you can walk the user through.

✨ Features

What Can It Do?

Property	Details
Post	`post_tweet`, `reply_to_tweet`, `quote_tweet`, `delete_tweet`. You can say things like "Post 'hello world' on X" or "Reply to this tweet saying thanks".
Read	`get_tweet`, `search_tweets`, `get_timeline`, `get_mentions`. For example, "Show me @elonmusk's latest posts" or "Search for tweets about MCP".
Users	`get_user`, `get_followers`, `get_following`. Such as "Look up @openai" or "Who does this user follow?".
Engage	`like_tweet`, `retweet`. You can say "Like that tweet" or "Retweet this".
Media	`upload_media`. For instance, "Upload this image and post it with the caption...".
Analytics	`get_metrics`. For example, "How many impressions did my last post get?".

It accepts tweet URLs or IDs interchangeably. You can paste https://x.com/user/status/123 or just 123.

📦 Installation

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 how to get them:

a) Create an app

Go to the X Developer Portal.
Sign in with your X account.
Go to Apps in the left sidebar.
Click Create App (you may need to sign up for a developer account first).
Give it a name (e.g., my-x-mcp).
You'll immediately see your Consumer Key (API Key), Secret Key (API Secret), and Bearer Token.
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.

In your app's page, scroll down to User authentication settings.
Click Set up.
Set App permissions to Read and write.
Set Type of App to Web App, Automated App or Bot.
Set Callback URI / Redirect URL to https://localhost (required but won't be used).
Set Website URL to any valid URL (e.g., https://x.com).
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:

Go back to your app's Keys and Tokens page.
Under Access Token and Secret, click Regenerate.
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

💻 Usage Examples

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.

OpenAI Codex

Option A: CLI

codex mcp add x-twitter --env X_API_KEY=your_consumer_key --env X_API_SECRET=your_secret_key --env X_ACCESS_TOKEN=your_access_token --env X_ACCESS_TOKEN_SECRET=your_access_token_secret --env X_BEARER_TOKEN=your_bearer_token -- node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

Option B: config.toml Add to ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

[mcp_servers.x-twitter]
command = "node"
args = ["/ABSOLUTE/PATH/TO/x-mcp/dist/index.js"]

[mcp_servers.x-twitter.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"

Windsurf

Add to ~/.codeium/windsurf/mcp_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"
      }
    }
  }
}

You can also add it from Windsurf Settings > Cascade > MCP Servers.

Cline (VS Code)

Open Cline's MCP settings (click the MCP Servers icon in Cline's top nav > Configure), then add to cline_mcp_settings.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"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Other MCP Clients

This is a standard stdio MCP server. For any MCP-compatible client, point it at:

node /ABSOLUTE/PATH/TO/x-mcp/dist/index.js

With these environment variables: X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET, X_BEARER_TOKEN.

📚 Documentation

Troubleshooting

403 "oauth1-permissions" error when posting

Your Access Token was generated before you enabled write permissions. Go to the X Developer Portal, ensure App permissions are set to "Read and write", then Regenerate your Access Token and Secret.

401 Unauthorized

Double-check that all 5 credentials in your .env are correct and that there are no extra spaces or line breaks.

429 Rate Limited

The error message includes exactly when the rate limit resets. Wait until then, or reduce request frequency.

Reply fails with a permissions/restriction error

As of Feb 2024, X restricts programmatic replies via the API. You can only reply if the original author @mentions you or quotes your post. This applies to Free, Basic, Pro, and Pay-Per-Use tiers (Enterprise is exempt). Use quote_tweet as a workaround.

Server shows "Connected" but tools aren't used

Make sure you added the server with the correct scope (user/global, not project-scoped if you want it everywhere), then restart your client.

Rate Limiting

Every response includes rate limit info: remaining requests, total limit, and reset time. When a limit is hit, you get a clear error with the exact reset timestamp.

Pagination

List endpoints return a next_token in the response. Pass it back to get the next page of results. Works on: search_tweets, get_timeline, get_mentions, get_followers, get_following.