How do I use twitter-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@twitter-mcp show me recent tweets about AI" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

twitter-mcp

by armatrix

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

twitter-mcp

A lightweight Twitter MCP server for Claude Code. Zero compilation — edit and run instantly with Bun.

Architecture

┌──────────────────────────────────────────────────────────────┐
│                       twitter-mcp v1.1                       │
│                        (MCP Server)                          │
├──────────────────────────────────────────────────────────────┤
│                    17 Tools + Media Upload                   │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│  │ search_tweets│ │ get_tweet    │ │ get_user             │ │
│  │ search_users │ │ get_article  │ │ get_user_timeline    │ │
│  │              │ │ get_replies  │ │ get_user_followers   │ │
│  │              │ │ get_quotes   │ │ get_user_following   │ │
│  │              │ │ get_thread   │ │ get_user_mentions    │ │
│  │              │ │ get_trends   │ │                      │ │
│  └──────┬───────┘ └──────┬──────┘ └──────┬───────────────┘ │
│         └────────────────┼───────────────┘                  │
│                          │                                  │
│                    API Router                                │
│         ┌────────────────┼─────────────────┐                │
│         ▼                ▼                  ▼               │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐        │
│  │twitterapi.io│  │Official API │  │Cookie Client │        │
│  │ (API Key)   │  │(OAuth 1.0a) │  │(ct0+auth)    │        │
│  │             │  │             │  │              │        │
│  │ 13 read     │  │ post_tweet  │  │ reply        │        │
│  │ tools       │  │ like/unlike │  │ fallback     │        │
│  │             │  │ retweet     │  │ (auto on 403)│        │
│  │             │  │ delete      │  │              │        │
│  │             │  │ media upload│  │              │        │
│  └─────────────┘  └─────────────┘  └──────────────┘        │
└──────────────────────────────────────────────────────────────┘

Why Hybrid API?

API	Auth	Cost	Use Case
twitterapi.io	API Key	~$0.15/1K calls	Read operations (search, timeline, user info)
Official Twitter API	OAuth 1.0a	Free tier	Write operations (post, like, retweet, delete)
Cookie (browser session)	ct0 + auth_token	Free	Reply fallback (Free tier OAuth blocks replies to non-interacted tweets)

Related MCP server: X (Twitter) MCP Server - Enhanced Edition

Setup

1. Install

git clone https://github.com/armatrix/twitter-mcp.git
cd twitter-mcp
bun install

2. Configure

mkdir -p ~/.twitter-mcp
cp config.example.json ~/.twitter-mcp/config.json

Edit ~/.twitter-mcp/config.json:

{
  "reader": {
    "provider": "twitterapi.io",
    "api_key": "your-twitterapi-io-key"
  },
  "writer": {
    "provider": "twitter-official",
    "api_key": "your-consumer-api-key",
    "api_secret_key": "your-consumer-api-secret",
    "access_token": "your-access-token",
    "access_token_secret": "your-access-token-secret"
  },
  "cookie": {
    "ct0": "your-ct0-cookie",
    "auth_token": "your-auth-token-cookie"
  },
  "defaults": {
    "timeline_count": 20,
    "search_count": 20
  }
}

Get credentials:

reader.api_key: twitterapi.io — sign up and copy API key
writer.*: Twitter Developer Portal → Create App → Keys and Tokens
cookie.*: Browser DevTools → Application → Cookies → x.com → copy ct0 and auth_token values

Cookie section is optional. If omitted, reply fallback is disabled and OAuth 403 errors on replies are returned as-is.

Open x.com in your browser and log in
Open DevTools (F12) → Application → Cookies → https://x.com
Copy the value of ct0 (CSRF token, rotates periodically)
Copy the value of auth_token (session token, long-lived)
Paste both into config.json under the cookie section

Note: ct0 rotates every few hours. When cookie auth starts failing, refresh it from the browser.

4. Add to Claude Code

claude mcp add twitter -- bun run /path/to/twitter-mcp/src/index.ts -config ~/.twitter-mcp/config.json

Verify:

claude mcp list

Tools

Read (13 tools — twitterapi.io)

Tool	Description
`search_tweets`	Search tweets by keyword (advanced search syntax)
`search_users`	Search users by keyword
`get_tweet`	Get tweets by ID (supports comma-separated multiple IDs, includes viewCount)
`get_article`	Get X Article full content by tweet ID
`get_tweet_replies`	Get replies to a tweet
`get_tweet_quotes`	Get quote tweets
`get_tweet_thread`	Get full thread context
`get_user`	Get user profile by username
`get_user_timeline`	Get user's recent tweets
`get_user_followers`	Get user's followers
`get_user_following`	Get accounts a user follows
`get_user_mentions`	Get tweets mentioning a user
`get_trends`	Get trending topics by region (WOEID)

Write (4 tools — Official Twitter API, OAuth 1.0a)

Tool	Description
`post_tweet`	Post a tweet with optional images, reply, quote-tweet. Auto-fallback to cookie auth on reply 403.
`like_tweet`	Like a tweet by ID
`unlike_tweet`	Remove a like from a tweet
`retweet`	Retweet a tweet by ID
`delete_tweet`	Delete a tweet by ID

Reply Fallback Flow

post_tweet(text, reply_to_tweet_id)
  │
  ▼
OAuth 1.0a POST /2/tweets
  │
  ├─ 200 OK → return result (method: "oauth")
  │
  └─ 403 Forbidden (Free tier reply restriction)
       │
       ▼
     Cookie client configured?
       │
       ├─ Yes → GraphQL CreateTweet → return result (method: "cookie")
       │
       └─ No → return error

Image upload: Pass media_paths with up to 4 local file paths (png/jpg/gif/webp). Images are uploaded via Twitter v1.1 media endpoint, then attached to the tweet.

post_tweet(
  text: "Hello world",
  media_paths: ["/path/to/screenshot.png", "/path/to/chart.jpg"]
)

Known Limitations

Issue	Workaround
Official API Free tier blocks replies to non-interacted tweets (403)	Cookie fallback auto-handles this
`ct0` cookie rotates every few hours	Re-extract from browser when cookie auth fails
`get_user_timeline` / `get_tweet` via twitterapi.io don't return views/impressions	Use `get_tweet` (which goes through twitterapi.io) — it returns `viewCount`
Cookie client doesn't support image upload	Images only via OAuth `post_tweet` (no fallback for image+reply combo)

Development

No build step required. Edit any .ts file and restart the MCP server.

# Run directly
bun run src/index.ts -config ~/.twitter-mcp/config.json

# Type check
bun build src/index.ts --target=bun

Project Structure

src/
├── index.ts              # MCP server entry point
├── config.ts             # Config types and loader
├── clients/
│   ├── reader.ts         # twitterapi.io client (read operations)
│   ├── writer.ts         # Official Twitter API client (OAuth 1.0a write)
│   └── cookie.ts         # Cookie-based client (GraphQL, reply fallback)
└── tools/
    ├── search.ts         # search_tweets, search_users
    ├── tweets.ts         # get_tweet, get_article, get_replies, get_quotes, get_thread
    ├── users.ts          # get_user, get_timeline, get_followers, get_following, get_mentions
    ├── discovery.ts      # get_trends
    └── write.ts          # post_tweet, like_tweet, unlike_tweet, retweet, delete_tweet

Tech Stack

Runtime: Bun
MCP SDK: @modelcontextprotocol/sdk
OAuth: oauth-1.0a (Official API auth)
Cookie Auth: Direct fetch + Twitter internal GraphQL (no external deps)

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

twitterapi-mcp-server A
io.github.kaitoInfra
Twitter/X read-only MCP server — 12 tools: search, users, tweets, followers, timelines, trends.
Social Media Search
121
mcp-server A
io.twitterapi
Official twitterapi.io hosted MCP: Twitter/X tweets, users, followers, trends. OAuth or API key.
Social Media Search
1211
TwitterAPIsOAuth
io.github.TwitterAPIs
Official MCP server for twitterapis.com. Read and write Twitter/X: search, users, tweets, DMs.
Social Media Communication Search
1
excalibur-mcp A
io.github.lonniev
FastMCP server for posting formatted content to X (Twitter) — Tollbooth-monetized, DPYC-native
Social Media Communication
8723

Related MCP Servers

Twitter MCP Server
Social Media Search
EnesCinr
A
license
B
quality
D
maintenance
An MCP server that enables Claude to interact with Twitter, allowing for posting tweets and searching Twitter content.
Updated a year ago (2025-07-17 18:49 UTC)
2
325 npm
408
MIT
X (Twitter) MCP Server -
Social Media Communication
mbelinky
A
license
Not graded
quality
F
maintenance
An enhanced Model Context Protocol server that enables Claude to interact with Twitter/X, supporting tweet posting, searching, and deletion with both OAuth 1.0a and OAuth 2.0 authentication methods.
Updated a year ago (2025-06-27 20:21 UTC)
111 npm
24
MIT
Twitter MCP Server
Social Media Communication
aali-1
A
license
Not graded
quality
D
maintenance
Model Context Protocol server that enables programmatic interaction with Twitter API, allowing users to post tweets, search for content, and retrieve user timelines through standardized MCP tools.
Updated a year ago (2025-08-06 02:09 UTC)
14 npm
MIT
X(Twitter) V2 MCP Server
Social Media Search
NexusX-MCP
A
license
Not graded
quality
D
maintenance
An MCP server for interacting with the Twitter/X API v2, enabling AI assistants to retrieve tweets, post content, reply, quote, and more programmatically.
Updated a year ago (2025-04-20 13:28 UTC)
1,462 npm
13
MIT

twitter-mcp

Architecture

Why Hybrid API?

Setup

1. Install

2. Configure

3. Get Cookie Credentials

4. Add to Claude Code

Tools

Read (13 tools — twitterapi.io)

Write (4 tools — Official Twitter API, OAuth 1.0a)

Reply Fallback Flow

Known Limitations

Development

Project Structure

Tech Stack

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Twitter MCP Server

X (Twitter) MCP Server -

Twitter MCP Server

X(Twitter) V2 MCP Server