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
Prerequisites
Installation
Getting Your Twitter Cookies
Configuration
Tools Reference
- Read Operations
- Write Operations
Response Formats
Development
Architecture
Troubleshooting
Disclaimer
License

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:

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

Cookie	Description
`auth_token`	Your session authentication token
`ct0`	CSRF protection token

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

Variable	Required	Description
`TWITTER_AUTH_TOKEN`	Yes	The `auth_token` cookie from your Twitter session
`TWITTER_CT0`	Yes	The `ct0` CSRF cookie from your Twitter session

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.

Parameter	Type	Default	Description
`count`	number	20	Number of tweets to fetch (1-100)

`get_user_profile`

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

Parameter	Type	Description
`username`	string	Twitter username without the `@` symbol

`get_user_tweets`

Get recent tweets posted by a specific user.

Parameter	Type	Default	Description
`username`	string	—	Twitter username without `@`
`count`	number	20	Number of tweets to fetch (1-100)

`get_tweet`

Get a single tweet by its ID.

Parameter	Type	Description
`tweet_id`	string	The tweet ID

`search_tweets`

Search for tweets matching a query. Supports Twitter search operators (from:, to:, has:, filter:, etc.).

Parameter	Type	Default	Description
`query`	string	—	Search query string
`count`	number	20	Number of results (1-100)

Search operator examples:

from:elonmusk — tweets from a specific user
to:openai — tweets directed at a user
"exact phrase" — exact phrase match
has:media — tweets containing media
filter:links — tweets containing links
lang:en — filter by language
since:2024-01-01 until:2024-12-31 — date range

`get_trends`

Get current trending topics on Twitter. Takes no parameters.

Write Operations

`post_tweet`

Post a new tweet. Can also reply to an existing tweet.

Parameter	Type	Description
`text`	string	Tweet text (1-280 characters)
`reply_to_tweet_id`	string?	Optional tweet ID to reply to

`like_tweet`

Like a tweet by its ID.

Parameter	Type	Description
`tweet_id`	string	The tweet ID to like

`unlike_tweet`

Remove a like from a tweet.

Parameter	Type	Description
`tweet_id`	string	The tweet ID to unlike

`retweet`

Retweet a tweet by its ID.

Parameter	Type	Description
`tweet_id`	string	The tweet ID to retweet

`unretweet`

Remove a retweet.

Parameter	Type	Description
`tweet_id`	string	The tweet ID to unretweet

`reply_to_tweet`

Reply to a specific tweet.

Parameter	Type	Description
`tweet_id`	string	The tweet ID to reply to
`text`	string	Reply text (1-280 characters)

Response Formats

All tools return clean, parsed JSON instead of raw Twitter GraphQL responses.

Tweet Object

{
  "id": "1234567890",
  "text": "Hello world!",
  "author": {
    "id": "9876543210",
    "username": "johndoe",
    "name": "John Doe",
    "profile_image_url": "https://pbs.twimg.com/...",
    "verified": true
  },
  "created_at": "Mon Jan 27 12:00:00 +0000 2025",
  "likes": 42,
  "retweets": 12,
  "replies": 5,
  "quotes": 3,
  "bookmarks": 7,
  "views": 1500,
  "language": "en",
  "conversation_id": "1234567890",
  "media": [
    {
      "type": "photo",
      "url": "https://pbs.twimg.com/media/...",
      "preview_url": "https://pbs.twimg.com/media/..."
    }
  ]
}

User Profile Object

{
  "id": "9876543210",
  "username": "johndoe",
  "name": "John Doe",
  "description": "Software engineer & builder",
  "profile_image_url": "https://pbs.twimg.com/...",
  "profile_banner_url": "https://pbs.twimg.com/...",
  "followers_count": 1500,
  "following_count": 300,
  "tweet_count": 4200,
  "verified": true,
  "created_at": "Tue Mar 15 00:00:00 +0000 2020",
  "location": "San Francisco, CA",
  "url": "https://example.com"
}

Trend Item Object

{
  "name": "#TrendingTopic",
  "tweet_count": 125000,
  "description": "125K posts",
  "domain": "Technology"
}

Development

# 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

twitter-mcp/
├── src/
│   ├── index.ts              # MCP server entry, tool registration
│   ├── twitter-client.ts     # Twitter API client, auth, request/response handling
│   └── types.ts              # TypeScript interfaces (Tweet, UserProfile, TrendItem)
├── build/                    # Compiled JavaScript output
├── package.json
├── tsconfig.json
├── .env.example
└── .gitignore

Architecture

┌─────────────────┐     stdio      ┌─────────────────┐
│   MCP Client    │ ◄────────────► │  twitter-mcp    │
│ (Claude, etc.)  │   JSON-RPC     │  MCP Server     │
└─────────────────┘                └────────┬────────┘
                                            │
                              ┌─────────────┴─────────────┐
                              │                           │
                      ┌───────▼───────┐          ┌────────▼────────┐
                      │  undici HTTP  │          │   Puppeteer +   │
                      │  (Read ops)   │          │   Stealth       │
                      │  Fast, direct │          │   (Write ops)   │
                      └───────┬───────┘          └────────┬────────┘
                              │                           │
                              └─────────────┬─────────────┘
                                            │
                                   ┌────────▼────────┐
                                   │   x.com API     │
                                   │   (GraphQL)     │
                                   └─────────────────┘

How it works:

The server uses a dual-engine approach to handle Twitter's anti-bot detection:

Read operations (timeline, search, profiles) use fast direct HTTP requests via undici — no browser needed
Write operations (post, like, retweet, reply) use a headless Puppeteer browser with the stealth plugin to bypass Twitter's automation detection (error 226)

The stealth browser launches lazily on the first write call and stays alive for subsequent operations.

Authentication:

Cookies (auth_token + ct0) are set on the browser session and HTTP client
ct0 is automatically refreshed when Twitter rotates it
CSRF mismatches are detected and retried transparently

Troubleshooting

"Missing required environment variables"

Both TWITTER_AUTH_TOKEN and TWITTER_CT0 must be set. Double-check your Claude Desktop config or .env file.

HTTP 401 / 403 errors

Your cookies have expired. Extract fresh cookies from your browser following the instructions above.

HTTP 429 errors

You've hit Twitter's rate limit. Wait a few minutes before trying again. Different endpoints have different rate limits.

Empty responses / no tweets returned

Twitter occasionally changes GraphQL query IDs when deploying updates. The hardcoded query IDs in src/twitter-client.ts may need to be refreshed. You can extract current query IDs from Twitter's web client JavaScript bundles using browser DevTools (Network tab → filter by graphql).

Error 226 "This request looks like it might be automated"

Write operations use a stealth Puppeteer browser to bypass this. If you still see this error, your account may have temporary restrictions — try posting manually once from your browser, then retry.

Browser launch failures

The first write operation launches a Chromium browser. Ensure you have enough memory and that Puppeteer's bundled Chromium was downloaded during npm install. On Linux servers, you may need additional system libraries — see Puppeteer troubleshooting.

Server won't start in Claude Desktop

Ensure the path in your config uses absolute paths
On Windows, use forward slashes (C:/Users/...) or escaped backslashes (C:\\Users\\...)
Check Claude Desktop logs for error messages

Disclaimer

This server uses Twitter's internal, undocumented GraphQL API through cookie-based session authentication. This is not the official Twitter API.

Twitter may change endpoints, query IDs, or authentication requirements at any time
Automated use of Twitter via cookies may violate Twitter's Terms of Service
Use at your own risk and responsibility
This project is intended for personal use and educational purposes

License

ISC

Twitter/X MCP Server

Twitter/X MCP Server

Table of Contents

Features

Prerequisites

Installation

Getting Your Twitter Cookies

Configuration

Claude Desktop

Claude Code (CLI)

Environment Variables

Tools Reference

Read Operations

get_home_timeline

get_user_profile

get_user_tweets

get_tweet

search_tweets

get_trends

Write Operations

post_tweet

like_tweet

unlike_tweet

retweet

unretweet

reply_to_tweet

Response Formats

Tweet Object

User Profile Object

Trend Item Object

Development

Project Structure

Architecture

Troubleshooting

"Missing required environment variables"

HTTP 401 / 403 errors

HTTP 429 errors

Empty responses / no tweets returned

Error 226 "This request looks like it might be automated"

Browser launch failures

Server won't start in Claude Desktop

Disclaimer

License

Reviews

`get_home_timeline`

`get_user_profile`

`get_user_tweets`

`get_tweet`

`search_tweets`

`get_trends`

`post_tweet`

`like_tweet`

`unlike_tweet`

`retweet`

`unretweet`

`reply_to_tweet`