Twitter/X MCP Server

Twitter/X MCP Server

A Model Context Protocol (MCP) server that connects AI assistants to Twitter/X using cookie-based authentication. Provides 12 tools for reading timelines, searching tweets, posting, liking, retweeting, and more — all through Twitter's internal GraphQL API.

Built with TypeScript, @modelcontextprotocol/sdk, and Zod for runtime validation.

Features

• Full Twitter access — Read timelines, search, view profiles, post tweets, like, retweet, reply
• Cookie-based auth — No Twitter Developer account or OAuth app required
• Anti-bot bypass — Write operations use Puppeteer with stealth plugin to bypass Twitter's automation detection
• Dual-engine — Fast HTTP for reads, headless browser for writes
• Clean responses — Deeply nested Twitter GraphQL responses are parsed into simple, readable JSON
• Type-safe — Written in strict TypeScript with Zod schema validation on all tool inputs
• Auto ct0 refresh — CSRF tokens are refreshed transparently when Twitter rotates them
• MCP standard — Works with any MCP-compatible client (Claude Desktop, Claude Code, etc.)

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0
• A Twitter/X account with an active session in your browser

Installation

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

# Install dependencies
npm install

# Build
npm run build

Getting Your Twitter Cookies

The server authenticates using two cookies from your logged-in Twitter session. Here's how to extract them:

1. Open x.com in your browser and log in
2. Open Developer Tools (F12 or Ctrl+Shift+I)
3. Go to the Application tab (Chrome/Edge) or Storage tab (Firefox)
4. In the left sidebar, expand Cookies and click on https://x.com
5. Find and copy these two cookie values:

Important: Both cookies must come from the same active session. If you log out or the session expires, you'll need to extract fresh cookies.

Configuration

Claude Desktop

Add the server to your Claude Desktop config file:

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

{
  "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"
      }
    }
  }
}

Claude Code (CLI)

Add to your Claude Code MCP settings (.claude/settings.json or via claude mcp add):

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

Then set the environment variables before launching, or use a .env file in the project directory.

Environment Variables

You can also create a .env file in the project root:

TWITTER_AUTH_TOKEN=your_auth_token_here
TWITTER_CT0=your_ct0_here

Tools Reference

Read Operations

`get_home_timeline`

Fetch tweets from the authenticated user's home timeline.

`get_user_profile`

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

`get_user_tweets`

Get recent tweets posted by a specific user.

`get_tweet`

Get a single tweet by its ID.