home / mcp / twitter/x mcp server

Twitter/X MCP Server

Provides read and write tools to access Twitter/X via cookie-based authentication and GraphQL endpoints.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "aditya-ai-architect-twitter-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/twitter-mcp/build/index.js"
      ],
      "env": {
        "TWITTER_CT0": "your_ct0_here",
        "TWITTER_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

You can run a dedicated Model Context Protocol (MCP) server that connects AI assistants to Twitter/X using cookie-based authentication. It exposes read and write tools for timelines, searches, posting, liking, and more, while keeping responses clean and easy to parse for your MCP clients.

How to use

You will run the MCP server locally and connect it to your MCP client, such as Claude Desktop or Claude Code. The server handles read operations over fast HTTP and performs write operations through a stealth-enabled headless browser to bypass automated-detection mechanisms. You can perform actions like reading timelines, searching tweets, posting, liking, retweeting, and replying. Authentication relies on cookies from your active Twitter session, which you provide to the server.

To start using the server from your MCP client, configure the client to load the server as an MCP endpoint. The server exposes a set of tools you can invoke through the MCP protocol, such as reading timelines and posting tweets. Ensure your client passes the appropriate parameters to each tool, and rely on the server to manage authentication cookies and token refreshes automatically.

How to install

Prerequisites you need before installation:

Node.js >= 18.0.0

npm >= 8.0.0

A Twitter/X account with an active session in your browser

Then follow these steps to install and build the MCP server locally:

# Clone the repository
git clone https://github.com/aditya-ai-architect/twitter-mcp.git
cd twitter-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Configure how you connect your MCP client to this Twitter MCP server. The examples below show how to add the server to Claude Desktop and Claude Code, including the required environment variables that hold your Twitter session cookies.

{
  "mcpServers": {
    "twitter": {
      "command": "node",
      "args": ["/absolute/path/to/twitter-mcp/build/index.js"],
      "env": {
        "TWITTER_AUTH_TOKEN": "your_auth_token_here",
        "TWITTER_CT0": "your_ct0_here"
      }
    }
  }
}

Additionally, you can run the server from Claude Code by referencing the same node entry point in your MCP settings and exporting the environment variables before launch.

claude mcp add twitter -- node /absolute/path/to/twitter-mcp/build/index.js

Environment variables you must provide (as shown):

TWITTER_AUTH_TOKEN=your_auth_token_here
TWITTER_CT0=your_ct0_here

Tip: you can also place these values in a .env file in the project directory and load them when starting the server.

Security and cookies

The server authenticates using two cookies from your logged-in Twitter session. It stores these cookies in both the HTTP client and the browser session used for write operations. The CSRF token (ct0) is refreshed automatically when Twitter rotates it, and any CSRF mismatches are retried transparently.

Because you are using cookie-based authentication, you should keep your cookies secure and avoid sharing them. Use a dedicated user/session for the MCP activities and rotate cookies if you suspect exposure.

Troubleshooting

If you encounter missing environment variables, ensure both TWITTER_AUTH_TOKEN and TWITTER_CT0 are set for your MCP client and server configuration.

HTTP 401/403 indicates expired cookies; refresh them from your browser and update the server configuration.

HTTP 429 means you hit Twitter’s rate limits. Pause and retry after a short delay. Different tools have different limits.

If you receive an error about automated access (error 226), the server’s stealth browser should bypass this for write operations. If problems persist, try posting manually from your browser to reestablish any temporary restrictions, then retry.

Development

Development commands you can use during iteration.

# Watch mode — recompiles on file changes
npm run dev

# Build once
npm run build

# Run directly (requires env vars)
npm start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node build/index.js

Project structure shows source and build outputs, including the MCP server entry and the Twitter client logic.

Notes on architecture and capabilities

This MCP server uses a dual-engine approach to balance speed and reliability. Read operations leverage fast HTTP requests, while write operations use a headless browser with a stealth plugin to bypass automation detection. All responses are parsed into clean JSON for easy consumption by MCP clients.

Disclaimer

This server interacts with Twitter using cookie-based sessions and internal GraphQL endpoints. It is not the official Twitter API, and usage should comply with Twitter’s terms and applicable laws.

Available tools

get_home_timeline

Fetch tweets from the authenticated user's home timeline with optional limit.

get_user_profile

Retrieve a Twitter user's profile information by their username.

get_user_tweets

Get recent tweets from a specific user by username with an optional count.

get_tweet

Fetch a single tweet by its ID.

search_tweets

Search tweets matching a query with optional result count.

get_trends

Return current trending topics on Twitter.

post_tweet

Post a new tweet or reply to an existing one.

like_tweet

Like a tweet by its ID.

unlike_tweet

Remove a like from a tweet.

retweet

Retweet a tweet by its ID.

unretweet

Remove a retweet from a tweet.

reply_to_tweet

Reply to a specific tweet with text.