x-twitter

X (Twitter) MCP server exposes a set of tools to interact with Twitter API v2 through natural language commands in MCP-enabled AI tools. Once running, you can invoke capabilities such as posting tweets, fetching user profiles and follower/following lists, searching tweets and trends, managing bookmarks and timelines, and deleting or liking tweets. The tools are exposed via RPC-compatible endpoints over Streamable HTTP, SSE, or STDIO, depending on how you run the server. Typical usage involves authenticating with your Twitter API credentials (via environment variables or a provided config payload) and then issuing JSON-RPC requests to the server’s /mcp endpoint to call methods like get_user_profile, post_tweet, search_twitter, get_followers, and others.

To get started, install the package, run the server, and configure Claude Desktop or your MCP consumer to connect. You can pass a per-request config payload with credentials when initializing the MCP session, ensuring subsequent tool calls have access to the required Twitter credentials. The server implements a complete subset of Twitter API v2 endpoints relevant for user management, tweet management, timelines, and search functionality, with built-in rate limit handling.

Prerequisites:

• Python 3.10 or higher
• Access to a Twitter Developer account with API credentials (API Key, API Secret, Access Token, Access Token Secret, Bearer Token)
• Optional: a Claude Desktop setup if you plan to integrate with Claude, or any MCP tool that supports HTTP RPC

Installation steps (recommended):

1. Install the package from PyPI

pip install x-twitter-mcp

2. Run the MCP server (Streamable HTTP mode via Python module)

python -m x_twitter_mcp.http_server

3. If you prefer to run via a local module for a zero-configuration setup, set environment variables (see next step) and ensure dependencies are installed. Alternatively, install from source and use uv/Smithery integration as described in the README.

4. Set up environment variables (example):

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

5. If you need unbuffered output for logging in some clients, ensure PYTHONUNBUFFERED=1 is set in your environment.

Notes:

• The server exposes a per-request config payload via a base64-encoded config object (when using Smithery or Claude integrations). Include your Twitter credentials in that payload as needed for the session.

Tips and common considerations:

• Use a dedicated Twitter Developer App for MCP usage and rotate credentials as needed. Keep Bearer Token separate when using v2 endpoints.
• The server supports rate-limit handling; implement backoff logic in your client if you plan to run high-volume queries.
• For Claude Desktop users, you can embed credentials in Claude's MCP config (or rely on environment variables if running directly). Ensure you do not commit credentials to source control.
• If running locally with uv/Smithery, you may expose the MCP at /mcp for RPC calls and /sse for streaming events depending on your deployment.
• The npm_package field is null for this Python-based MCP server; if you deploy via an npm-based workflow, adjust the command accordingly.