Twitter/X MCP Server

A Model Context Protocol server that gives AI assistants full read/write access to Twitter/X through cookie-based authentication. No Developer account or OAuth app required.

Features

• 12 tools covering timelines, search, profiles, trends, posting, likes, retweets, and replies

• Cookie-based auth -- uses your browser session cookies, no Twitter API keys needed

• Dual-engine architecture -- fast HTTP via undici for reads, headless Puppeteer with stealth plugin for writes

• Anti-bot bypass -- puppeteer-extra-plugin-stealth avoids Twitter automation detection (error 226)

• Auto CSRF refresh -- ct0 tokens refreshed transparently when Twitter rotates them

• Clean JSON output -- nested GraphQL responses parsed into simple, structured objects

• Type-safe -- strict TypeScript with Zod schema validation on every tool input

• MCP standard -- works with Claude Desktop, Claude Code, and any MCP-compatible client

Prerequisites

• Node.js >= 18.0.0

• npm >= 8.0.0

• A Twitter/X account with an active browser session

Installation

git clone https://github.com/aditya-ai-architect/twitter-mcp.git
cd twitter-mcp
npm install
npm run build

Getting Your Twitter Cookies

1. Open x.com and log in

2. Open Developer Tools (F12)

3. Go to Application > Cookies > https://x.com

4. Copy these two values:

Both cookies must come from the same active session.

Configuration

Environment Variables

Create a .env file in the project root:

TWITTER_AUTH_TOKEN=your_auth_token_here
TWITTER_CT0=your_ct0_here

Claude Desktop

Add to your Claude Desktop config:

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

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

Tools

Read Operations

Write Operations

Architecture

MCP Client (Claude)  <--stdio-->  twitter-mcp Server
                                        |
                        +---------------+---------------+
                        |                               |
                 undici HTTP                    Puppeteer + Stealth
                 (Read ops)                    (Write ops)
                        |                               |
                        +---------------+---------------+
                                        |
                                  x.com GraphQL API

Read operations use direct HTTP for speed. Write operations use a headless browser with stealth to bypass automation detection.

Development

npm run dev      # Watch mode
npm run build    # Build once
npm start        # Run the server

Project Structure

twitter-mcp/
  src/
    index.ts              # MCP server setup and tool registration
    twitter-client.ts     # Twitter API client (HTTP + Puppeteer)
    types.ts              # TypeScript interfaces
  build/                  # Compiled output
  package.json
  tsconfig.json

Troubleshooting

Tech Stack

• Runtime: Node.js (ES2022)

• Language: TypeScript 5.x (strict mode)

• MCP SDK: @modelcontextprotocol/sdk

• HTTP Client: undici

• Browser: Puppeteer + puppeteer-extra-plugin-stealth

• Validation: Zod

License

ISC

Built by