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:

Cookie	Description
auth_token	Session authentication token
ct0	CSRF protection token

Both cookies must come from the same active session.

---

Configuration

Environment Variables

Variable	Required	Description
TWITTER_AUTH_TOKEN	Yes	The auth_token cookie value
TWITTER_CT0	Yes	The ct0 cookie value

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

Tool	Description
get_home_timeline	Fetch tweets from the authenticated user's home timeline
get_user_profile	Get a user profile by username
get_user_tweets	Get recent tweets from a specific user
get_tweet	Get a single tweet by ID
search_tweets	Search tweets with full operator support
get_trends	Get current trending topics

Write Operations

Tool	Description
post_tweet	Post a new tweet
like_tweet	Like a tweet
unlike_tweet	Remove a like
retweet	Retweet a tweet
unretweet	Remove a retweet
reply_to_tweet	Reply to a specific tweet

---

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

Issue	Solution
HTTP 401/403	Cookies expired -- extract fresh ones from browser
HTTP 429	Rate limited -- wait a few minutes
Error 226	Stealth browser handles this; if persistent, post manually once then retry
Empty responses	Twitter may have rotated GraphQL query IDs

---

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 Aditya Gaurav