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:

1. Clone the Repository:

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

2. Set Up a Virtual Environment (optional but recommended):

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

3. Install Dependencies:

Using `uv` (recommended, as the project uses `uv.lock`):

uv sync

Alternatively, using `pip`:

pip install .

4. Configure Environment Variables:

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

TWITTER_OAUTH2_USER_ACCESS_TOKEN=your_oauth2_user_token

See Obtaining an OAuth 2.0 User Token below.

Obtaining an OAuth 2.0 User Token

The bookmark endpoints (`GET /2/users/:id/bookmarks`, `DELETE /2/users/:id/bookmarks/:tweet_id`) require OAuth 2.0 User Context — they reject both app-only bearer tokens and OAuth 1.0a. You need to perform the PKCE authorization flow once to obtain a user-scoped token.

Steps

1. In the Twitter Developer Portal, open your app → Settings → User authentication settings and enable OAuth 2.0. Set a callback URL (e.g. `https://localhost/`).

2. Run the PKCE flow using Tweepy:

import tweepy

handler = tweepy.OAuth2UserHandler(
    client_id="YOUR_CLIENT_ID",       # OAuth 2.0 Client ID (from Developer Portal)
    redirect_uri="https://localhost/",
    scope=["bookmark.read", "bookmark.write", "users.read", "offline.access"],
    client_secret="YOUR_CLIENT_SECRET",  # Optional for public clients
)

print(handler.get_authorization_url())
# Open the URL, authorize, copy the redirected URL, then:
redirected_url = input("Paste redirected URL: ")
token = handler.fetch_token(redirected_url)
print(token["access_token"])

3. Set the resulting token as `TWITTER_OAUTH2_USER_ACCESS_TOKEN` in your environment or `.env` file.

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.

1. Build the Docker image:

docker build -t x-twitter-mcp .

2. Run the container (Smithery uses PORT; default here is 8081):

docker run -p 8081:8081 -e PORT=8081 x-twitter-mcp

3. Endpoints:

4. 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",
        "TWITTER_OAUTH2_USER_ACCESS_TOKEN": "your_oauth2_user_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.

OpenClaw Companion Workflow

This MCP server is best when an MCP client should call Twitter API v2 tools directly. If the workflow runs in OpenClaw and needs plugin install metadata, endpoint discovery, monitor alerts, webhooks, giveaway draws, media upload or download workflows, direct messages, follower export, or approval-gated post and reply actions, use TweetClaw as a separate OpenClaw plugin and pass reviewed tweet IDs or URLs between the tools.

See OpenClaw Companion Workflow for a command flow that keeps credentials separate and avoids duplicate write actions.

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: DESTRUCTIVE AND IRREVERSIBLE. Permanently deletes ALL bookmarks by fetching every page and removing them one by one. Requires `TWITTER_OAUTH2_USER_ACCESS_TOKEN`.
• Claude Desktop Example:

Delete all my Twitter bookmarks.

Claude will confirm with the user first, then delete all bookmarks and report the count.

`get_bookmarks`

• Description: Retrieves the authenticated user's bookmarked tweets. Returns up to 100 tweets per call; use the `cursor` parameter for pagination. Requires `TWITTER_OAUTH2_USER_ACCESS_TOKEN`.
• Claude Desktop Example:

Show my Twitter bookmarks, limit to 25.

Claude will return up to 25 bookmarked tweets, including ID, text, creation date, and author ID.

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:

• Claude Not Detecting the Server:

• Rate Limit Errors:

• Bookmark tools return 403:

• Syntax Warnings:

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 - rafal@kult.io