X Platform Interaction Service (MCP)

This Model Context Protocol (MCP) server provides an AI-driven interface for interacting with the X (Twitter) platform using the modern Twitter API v2. It translates plain language directives into actionable API calls for fetching data, publishing content, and monitoring activity.

Core Capabilities

• Retrieve extensive details for specified user accounts, including their follower and following lists.
• Execute commands for publishing, archiving (deleting), and marking tweets as favorites.
• Execute complex search operations for public tweets and discover current platform trends.
• Handle personal user state management, specifically for bookmark persistence.
• Integrated logic to gracefully manage Twitter API rate limits.
• Exclusively leverages the secure Twitter API v2 standard, utilizing credentials (API keys, tokens) to ensure maximum account safety and adherence to platform policies.
• Offers a complete backend implementation covering user, content, timeline, and search endpoints of API v2.

System Requirements

• Python Runtime: Version 3.10 or subsequent releases.
• X Developer Credentials: Access keys, secrets, access tokens, and a Bearer Token secured from the Twitter Developer Portal.
• Optional: Claude Desktop environment setup.
• Dependency management via tools like uv or standard pip.

Deployment Instructions

Method 1: Automated Installation via Smithery (Recommended for Desktop Clients)

Execute the following command to automatically configure the server for supported clients:

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

Method 2: Standard Python Installation (PyPI)

Install the core package directly using pip:

pip install x-twitter-mcp

Method 3: Source Code Compilation

1. Clone Source: Obtain the project files from the repository: bash git clone https://github.com/rafaljanicki/x-twitter-mcp-server.git cd x-twitter-mcp-server

2. Virtual Environment: Establish an isolated environment (optional but advised): bash python -m venv .venv source .venv/bin/activate # Windows counterpart: .venv\Scripts\activate

3. Install Dependencies: Utilize uv for fast dependency resolution: bash uv sync (Alternative: pip install .)

4. Credential Configuration: Populate the credentials file (typically .env): TWITTER_API_KEY=your_key_here TWITTER_API_SECRET=your_secret_here TWITTER_ACCESS_TOKEN=your_token TWITTER_ACCESS_TOKEN_SECRET=your_token_secret TWITTER_BEARER_TOKEN=your_bearer_token_value

Server Execution Modes

The preferred operational mode is Streamable HTTP, which leverages JSON-RPC over HTTP connections.

Mode A: Containerized HTTP Service (Docker)

1. Build the deployment artifact: bash docker build -t x-twitter-mcp .

2. Launch the service, mapping the internal port (default 8081): bash docker run -p 8081:8081 -e PORT=8081 x-twitter-mcp

3. Interaction Endpoints:

   • JSON-RPC Communication: POST http://localhost:8081/mcp
   • Status/Streaming Feed: GET http://localhost:8081/sse

4. For Smithery integration, configuration parameters are passed via a base64-encoded config query string appended to requests. Example initialization call: ```bash CONFIG_B64=$(printf '%s' '{"twitterApiKey":"...","twitterApiSecret":"...","twitterAccessToken":"...","twitterAccessTokenSecret":"...","twitterBearerToken":"..."}' | 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":{}}}' ```

Note: Use /mcp for RPC; / will result in a 404 error.

Mode B: Direct ASGI Execution (Local Host)

Execute the web server directly, bypassing Docker:

If installed via PyPI:

python -m x_twitter_mcp.http_server

If installed from source using uv:

uv run python -m x_twitter_mcp.http_server

Mode C: Standard Input/Output (STDIO) Bridge

For legacy desktop applications requiring STDIO communication:

If installed via PyPI:

x-twitter-mcp-server

If installed from source using uv:

uv run x-twitter-mcp-server

Integration with Claude Desktop

To enable Claude Desktop to utilize this service, specific configuration steps involving Node.js are necessary.

Prerequisite: Node.js Installation

Install Node.js from [nodejs.org] to support the underlying MCP host mechanism in the desktop client.

Configuration File Modification

Locate and edit the platform-specific configuration file:

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

Add the service definition under the mcpServers key. Select the structure based on your installation method.

If installed via PyPI (Direct Executable):

{
  "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 (Using uv):

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

Note on env: When using PyPI, environment variables must be explicitly declared in this configuration, as the .env file might be ignored.

Finalizing Setup

1. Terminate and restart Claude Desktop to load the updated configuration.
2. Verify connectivity by observing the tool/connector icon (often resembling a wrench) in the client interface.
3. Test functionality using prompts targeting tools like post_tweet or search_twitter.

Functional Tool Index

This section catalogs the specific operations exposed by the service.

User Account Operations

get_user_profile

• Purpose: Retrieve comprehensive profile metadata for a specified user identifier.
• Example Prompt: "Look up the complete X profile for user ID 123456789."

get_user_by_screen_name

• Purpose: Resolve user data using their unique handle (e.g., @username).
• Example Prompt: "Find the profile details for the user handle 'example_user'."

get_user_followers

• Purpose: List accounts that follow a target user.
• Example Prompt: "List the first 50 followers of user ID 123456789."

Content Manipulation Tools

post_tweet

• Purpose: Publish new textual updates to the platform, optionally including multimedia attachments.
• Example Prompt: "Publish a message: 'My first API interaction is a success! #AI'"

delete_tweet

• Purpose: Erase a previously published post given its ID.
• Example Prompt: "Remove the post identified by ID 123456789012345678."

favorite_tweet

• Purpose: Mark a specific tweet as 'Liked'.
• Example Prompt: "Apply a like to tweet ID 123456789012345678."

bookmark_tweet

• Purpose: Save a tweet to the user's private bookmark collection.
• Example Prompt: "Add tweet 123456789012345678 to my bookmarks."

Discovery and Feed Tools

search_twitter

• Purpose: Execute full-text searches across the platform's public data.
• Example Prompt: "Find the ten most recent posts concerning the topic 'quantum computing'."

get_trends

• Purpose: Fetch the currently trending topics within the service's configured location.
• Example Prompt: "Report on the top ten items currently trending globally."

get_timeline

• Purpose: Retrieve posts from the user's 'For You' algorithmically curated feed.
• Example Prompt: "Display the last 20 posts from my 'For You' feed."

Operational Notes & Support

• Starting Issues: Verify that all required authentication credentials are correctly supplied in the execution environment (.env or claude_desktop_config.json).
• Client Detection Failure: Reconfirm path accuracy within claude_desktop_config.json and ensure Claude Desktop has been fully restarted.
• API Throttling: While handling is automated, excessive requests will still trigger temporary API cooling periods enforced by Twitter.

Licensing and Authorship

Codebase licensed under the permissive MIT License.

Author: Rafal Janicki - rafal@kult.io