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:

   • 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
     

   • To use bookmark tools (get_bookmarks, delete_all_bookmarks), also add an OAuth 2.0 user access 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:

   • Streamable HTTP (JSON-RPC over HTTP): POST http://localhost:8081/mcp
   • SSE (Server-Sent Events): GET http://localhost:8081/sse

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.

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:

  • 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).

• Bookmark tools return 403:

  • get_bookmarks and delete_all_bookmarks require TWITTER_OAUTH2_USER_ACCESS_TOKEN. App-only bearer tokens and OAuth 1.0a are rejected by the bookmarks endpoint.
  • See Obtaining an OAuth 2.0 User Token for setup instructions.

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