# X Twitter Mcp Server

> X/Twitter MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-rafaljanicki-x-twitter-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rafaljanicki](https://agentstack.voostack.com/s/rafaljanicki)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rafaljanicki](https://github.com/rafaljanicki)
- **Source:** https://github.com/rafaljanicki/x-twitter-mcp-server

## Install

```sh
agentstack add mcp-rafaljanicki-x-twitter-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# X (Twitter) MCP server

[](https://smithery.ai/server/@rafaljanicki/x-twitter-mcp-server)
[](https://badge.fury.io/py/x-twitter-mcp)

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](https://developer.twitter.com/).
- Optional: **Claude Desktop**: Download and install the Claude Desktop app from the [Anthropic website](https://www.anthropic.com/).
- 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](https://smithery.ai/server/@rafaljanicki/x-twitter-mcp-server):

```bash
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:

```bash
pip install x-twitter-mcp
```

### Option 3: Install from Source
If you prefer to install from the source repository:

1. **Clone the Repository**:
   ```bash
   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):
   ```bash
   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`):
   ```bash
   uv sync
   ```
   Alternatively, using `pip`:
   ```bash
   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](#obtaining-an-oauth-20-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](https://developer.twitter.com/), 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:

```python
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:
   ```bash
   docker build -t x-twitter-mcp .
   ```

2. Run the container (Smithery uses PORT; default here is 8081):
   ```bash
   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:
   ```json
   {"twitterApiKey":"...","twitterApiSecret":"...","twitterAccessToken":"...","twitterAccessTokenSecret":"...","twitterBearerToken":"..."}
   ```
   Encode and call `initialize`:
   ```bash
   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:
```bash
python -m x_twitter_mcp.http_server
```

If installed from source with `uv`:
```bash
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:
```bash
x-twitter-mcp-server
```

If installed from source with `uv`:
```bash
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](https://nodejs.org/).
- Verify installation:
  ```bash
  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:
```json
{
  "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`:
```json
{
  "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](examples/openclaw-tweetclaw-companion.md) 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 tim

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rafaljanicki](https://github.com/rafaljanicki)
- **Source:** [rafaljanicki/x-twitter-mcp-server](https://github.com/rafaljanicki/x-twitter-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rafaljanicki-x-twitter-mcp-server
- Seller: https://agentstack.voostack.com/s/rafaljanicki
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.