X (Twitter) MCP server

A Model Context Protocol (MCP) server for interacting with Twitter (X) via AI tools. This server allows you to fetch tweets, post tweets, search Twitter, manage followers, and more, all through natural language commands in AI Tools.

Features

Fetch user profiles, followers, and following lists.
Post, delete, and favorite tweets.
Search Twitter for tweets and trends.
Manage bookmarks and timelines.
Built-in rate limit handling for the Twitter API.
Uses Twitter API v2 with proper authentication (API keys and tokens), avoiding the username/password hack to minimize the risk of account suspensions.
Provides a complete implementation of Twitter API v2 endpoints for user management, tweet management, timelines, and search functionality.

Prerequisites

Python 3.10 or higher: Ensure Python is installed on your system.
Twitter Developer Account: You need API credentials (API Key, API Secret, Access Token, Access Token Secret, and Bearer Token) from the Twitter Developer Portal.
Optional: Claude Desktop: Download and install the Claude Desktop app from the Anthropic website.
Optional: Node.js (for MCP integration): Required for running MCP servers in Claude Desktop.
A package manager like uv or pip for Python dependencies.

Installation

Option 1: Installing via Smithery (Recommended)

To install X (Twitter) MCP server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @rafaljanicki/x-twitter-mcp-server --client claude

Option 2: Install from PyPI

The easiest way to install x-twitter-mcp is via PyPI:

pip install x-twitter-mcp

Option 3: Install from Source

If you prefer to install from the source repository:

Clone the Repository:

git clone https://github.com/rafaljanicki/x-twitter-mcp-server.git
cd x-twitter-mcp-server

Set Up a Virtual Environment (optional but recommended):

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install Dependencies: Using uv (recommended, as the project uses uv.lock):
```
uv sync
```
Alternatively, using pip:
```
pip install .
```

Configure Environment Variables:

Create a .env file in the project root (you can copy .env.example if provided).

Add your Twitter API credentials:

TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret
TWITTER_BEARER_TOKEN=your_bearer_token

Running the Server

Preferred transport is Streamable HTTP. Use one of the following:

Recommended: Streamable HTTP (Docker/Smithery)

Run the server as an HTTP service with Streamable HTTP and SSE endpoints.

Build the Docker image:
```
docker build -t x-twitter-mcp .
```
Run the container (Smithery uses PORT; default here is 8081):
```
docker run -p 8081:8081 -e PORT=8081 x-twitter-mcp
```
Endpoints:
- Streamable HTTP (JSON-RPC over HTTP): POST http://localhost:8081/mcp
- SSE (Server-Sent Events): GET http://localhost:8081/sse

Pass config per-request (recommended in Smithery) via base64-encoded config query parameter. Example config JSON:

{"twitterApiKey":"...","twitterApiSecret":"...","twitterAccessToken":"...","twitterAccessTokenSecret":"...","twitterBearerToken":"..."}

Encode and call initialize:

CONFIG_B64=$(printf '%s' '{"twitterApiKey":"YOUR_KEY","twitterApiSecret":"YOUR_SECRET","twitterAccessToken":"YOUR_TOKEN","twitterAccessTokenSecret":"YOUR_TOKEN_SECRET","twitterBearerToken":"YOUR_BEARER"}' | base64)

curl -sS -X POST "http://localhost:8081/mcp?config=${CONFIG_B64}" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"capabilities":{}}}'

Notes:

A POST / will return 404; use /mcp for Streamable HTTP and /sse for SSE.
When deployed via Smithery, smithery.yaml is configured for runtime: container and startCommand.type: http.

Streamable HTTP (Local, no Docker)

Run the ASGI server directly.

If installed from PyPI:

python -m x_twitter_mcp.http_server

If installed from source with uv:

uv run python -m x_twitter_mcp.http_server

Endpoints and config passing are the same as above.

Legacy STDIO (CLI Script)

The project also exposes a STDIO CLI script x-twitter-mcp-server for desktop clients that expect STDIO.

If installed from PyPI:

x-twitter-mcp-server

If installed from source with uv:

uv run x-twitter-mcp-server

Using with Claude Desktop

To use this MCP server with Claude Desktop, you need to configure Claude to connect to the server. Follow these steps:

Step 1: Install Node.js

Claude Desktop uses Node.js to run MCP servers. If you don’t have Node.js installed:

Download and install Node.js from nodejs.org.
Verify installation:
```
node --version
```

Step 2: Locate Claude Desktop Configuration

Claude Desktop uses a claude_desktop_config.json file to configure MCP servers.

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

If the file doesn’t exist, create it.

Step 3: Configure the MCP Server

Edit claude_desktop_config.json to include the x-twitter-mcp server. Replace /path/to/x-twitter-mcp-server with the actual path to your project directory (if installed from source) or the path to your Python executable (if installed from PyPI).

If installed from PyPI:

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "x-twitter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "TWITTER_API_KEY": "your_api_key",
        "TWITTER_API_SECRET": "your_api_secret",
        "TWITTER_ACCESS_TOKEN": "your_access_token",
        "TWITTER_ACCESS_TOKEN_SECRET": "your_access_token_secret",
        "TWITTER_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

If installed from source with uv:

{
  "mcpServers": {
    "x-twitter-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/x-twitter-mcp-server",
        "run",
        "x-twitter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

"command": "x-twitter-mcp-server": Uses the CLI script directly if installed from PyPI.
"env": If installed from PyPI, you may need to provide environment variables directly in the config (since there’s no .env file). If installed from source, the .env file will be used.
"env": {"PYTHONUNBUFFERED": "1"}: Ensures output is unbuffered for better logging in Claude.

Step 4: Restart Claude Desktop

Quit Claude Desktop completely.
Reopen Claude Desktop to load the new configuration.

Step 5: Verify Connection

Open Claude Desktop.
Look for a hammer or connector icon in the input area (bottom right corner). This indicates MCP tools are available.
Click the icon to see the available tools from x-twitter-mcp, such as post_tweet, search_twitter, get_user_profile, etc.

Step 6: Test with Claude

You can now interact with Twitter using natural language in Claude Desktop. Here are some example prompts:

Fetch a User Profile:
```
Get the Twitter profile for user ID 123456.
```
Claude will call the get_user_profile tool and return the user’s details.
Post a Tweet:
```
Post a tweet saying "Hello from Claude Desktop! #MCP"
```
Claude will use the post_tweet tool to post the tweet and confirm the action.
Search Twitter:
```
Search Twitter for recent tweets about AI.
```
Claude will invoke the search_twitter tool and return relevant tweets.
Get Trends:
```
What are the current trending topics on Twitter?
```
Claude will use the get_trends tool to fetch trending topics.

When prompted, grant Claude permission to use the MCP tools for the chat session.

Available Tools

Below is a list of all tools provided by the x-twitter-mcp server, along with example executions in Claude Desktop using natural language prompts.

User Management Tools

`get_user_profile`

Description: Get detailed profile information for a user.
Claude Desktop Example:
```
Get the Twitter profile for user ID 123456789.
```
Claude will return the user’s profile details, including ID, name, username, profile image URL, and description.

`get_user_by_screen_name`

Description: Fetches a user by screen name.
Claude Desktop Example:
```
Get the Twitter user with screen name "example_user".
```
Claude will return the user’s profile details.

`get_user_by_id`

Description: Fetches a user by ID.
Claude Desktop Example:
```
Fetch the Twitter user with ID 987654321.
```
Claude will return the user’s profile details.

`get_user_followers`

Description: Retrieves a list of followers for a given user.
Claude Desktop Example:
```
Get the followers of user ID 123456789, limit to 50.
```
Claude will return a list of up to 50 followers.

`get_user_following`

Description: Retrieves users the given user is following.
Claude Desktop Example:
```
Who is user ID 123456789 following? Limit to 50 users.
```
Claude will return a list of up to 50 users.

`get_user_followers_you_know`

Description: Retrieves a list of common followers.
Claude Desktop Example:
```
Get common followers for user ID 123456789, limit to 50.
```
Claude will return a list of up to 50 common followers (simulated by filtering followers).

`get_user_subscriptions`

Description: Retrieves a list of users to which the specified user is subscribed.
Claude Desktop Example:
```
Get the subscriptions for user ID 123456789, limit to 50.
```
Claude will return a list of up to 50 users (using following as a proxy for subscriptions).

Tweet Management Tools

`post_tweet`

Description: Post a tweet with optional media, reply, and tags.
Claude Desktop Example:
```
Post a tweet saying "Hello from Claude Desktop! #MCP"
```
Claude will post the tweet and return the tweet details.

`delete_tweet`

Description: Delete a tweet by its ID.
Claude Desktop Example:
```
Delete the tweet with ID 123456789012345678.
```
Claude will delete the tweet and confirm the action.

`get_tweet_details`

Description: Get detailed information about a specific tweet.
Claude Desktop Example:
```
Get details for tweet ID 123456789012345678.
```
Claude will return the tweet’s details, including ID, text, creation date, and author ID.

`create_poll_tweet`

Description: Create a tweet with a poll.

Claude Desktop Example:

Create a poll tweet with the question "What's your favorite color?" and options "Red", "Blue", "Green" for 60 minutes.

Claude will create the poll tweet and return the tweet details.

`vote_on_poll`

Description: Vote on a poll.
Claude Desktop Example:
```
Vote "Blue" on the poll in tweet ID 123456789012345678.
```
Claude will return a mock response (since Twitter API v2 doesn’t support poll voting).

`favorite_tweet`

Description: Favorites a tweet.
Claude Desktop Example:
```
Like the tweet with ID 123456789012345678.
```
Claude will favorite the tweet and confirm the action.

`unfavorite_tweet`

Description: Unfavorites a tweet.
Claude Desktop Example:
```
Unlike the tweet with ID 123456789012345678.
```
Claude will unfavorite the tweet and confirm the action.

`bookmark_tweet`

Description: Adds the tweet to bookmarks.
Claude Desktop Example:
```
Bookmark the tweet with ID 123456789012345678.
```
Claude will bookmark the tweet and confirm the action.

`delete_bookmark`

Description: Removes the tweet from bookmarks.
Claude Desktop Example:
```
Remove the bookmark for tweet ID 123456789012345678.
```
Claude will remove the bookmark and confirm the action.

`delete_all_bookmarks`

Description: Deletes all bookmarks.
Claude Desktop Example:
```
Delete all my Twitter bookmarks.
```
Claude will delete all bookmarks and confirm the action.

Timeline & Search Tools

`get_timeline`

Description: Get tweets from your home timeline (For You).
Claude Desktop Example:
```
Show my Twitter For You timeline, limit to 20 tweets.
```
Claude will return up to 20 tweets from your For You timeline.

`get_latest_timeline`

Description: Get tweets from your home timeline (Following).
Claude Desktop Example:
```
Show my Twitter Following timeline, limit to 20 tweets.
```
Claude will return up to 20 tweets from your Following timeline.

`search_twitter`

Description: Search Twitter with a query.
Claude Desktop Example:
```
Search Twitter for recent tweets about AI, limit to 10.
```
Claude will return up to 10 recent tweets about AI.

`get_trends`

Description: Retrieves trending topics on Twitter.
Claude Desktop Example:
```
What are the current trending topics on Twitter? Limit to 10.
```
Claude will return up to 10 trending topics.

`get_highlights_tweets`

Description: Retrieves highlighted tweets from a user’s timeline.
Claude Desktop Example:
```
Get highlighted tweets from user ID 123456789, limit to 20.
```
Claude will return up to 20 tweets from the user’s timeline (simulated as highlights).

`get_user_mentions`

Description: Get tweets mentioning a specific user.
Claude Desktop Example:
```
Get tweets mentioning user ID 123456789, limit to 20.
```
Claude will return up to 20 tweets mentioning the user.

Troubleshooting

Server Not Starting:
- Ensure your .env file has all required Twitter API credentials (if installed from source).
- If installed from PyPI, ensure environment variables are set in claude_desktop_config.json or your shell.
- Check the terminal output for errors when running x-twitter-mcp-server.
- Verify that uv or your Python executable is correctly installed and accessible.
Claude Not Detecting the Server:
- Confirm the path in claude_desktop_config.json is correct.
- Ensure the command and args point to the correct executable and script.
- Restart Claude Desktop after updating the config file.
- Check Claude’s Developer Mode logs (Help → Enable Developer Mode → Open MCP Log File) for errors.
Rate Limit Errors:
- The server includes rate limit handling, but if you hit Twitter API limits, you may need to wait for the reset window (e.g., 15 minutes for tweet actions).
Syntax Warnings:
- If you see SyntaxWarning messages from Tweepy, they are due to docstring issues in Tweepy with Python 3.13. The server includes a warning suppression to handle this.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on the GitHub repository.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Rafal Janicki - [email protected]

X推特

X (Twitter) MCP server

Features

Prerequisites

Installation

Option 1: Installing via Smithery (Recommended)

Option 2: Install from PyPI

Option 3: Install from Source

Running the Server

Recommended: Streamable HTTP (Docker/Smithery)

Streamable HTTP (Local, no Docker)

Legacy STDIO (CLI Script)

Using with Claude Desktop

Step 1: Install Node.js

Step 2: Locate Claude Desktop Configuration

Step 3: Configure the MCP Server

Step 4: Restart Claude Desktop

Step 5: Verify Connection

Step 6: Test with Claude

Available Tools

User Management Tools

get_user_profile

get_user_by_screen_name

get_user_by_id

get_user_followers

get_user_following

get_user_followers_you_know

get_user_subscriptions

Tweet Management Tools

post_tweet

delete_tweet

get_tweet_details

create_poll_tweet

vote_on_poll

favorite_tweet

unfavorite_tweet

bookmark_tweet

delete_bookmark

delete_all_bookmarks

Timeline & Search Tools

get_timeline

get_latest_timeline

search_twitter

get_trends

get_highlights_tweets

get_user_mentions

Troubleshooting

Contributing

License

Author

MCP Now 重磅来袭，抢先一步体验

`get_user_profile`

`get_user_by_screen_name`

`get_user_by_id`

`get_user_followers`

`get_user_following`

`get_user_followers_you_know`

`get_user_subscriptions`

`post_tweet`

`delete_tweet`

`get_tweet_details`

`create_poll_tweet`

`vote_on_poll`

`favorite_tweet`

`unfavorite_tweet`

`bookmark_tweet`

`delete_bookmark`

`delete_all_bookmarks`

`get_timeline`

`get_latest_timeline`

`search_twitter`

`get_trends`

`get_highlights_tweets`

`get_user_mentions`