twitterapi.mcp

MCP server that exposes twitterapi.io endpoints as tools for AI agents and MCP hosts. Written in TypeScript, distributed on npm, runnable with a single npx command.

Current Tools

Tool	Description	API Endpoint	Auth
get_user_mentions	Fetch tweets mentioning a user.	GET /twitter/user/mentions	API key
get_tweet_thread_context	Fetch a page of the conversation thread around a tweet.	GET /twitter/tweet/thread_context	API key
create_tweet	Create a tweet or reply.	POST /twitter/create_tweet_v2	API key + cookies + proxy
delete_tweet	Delete one of your tweets.	POST /twitter/delete_tweet_v2	API key + cookies + proxy

Quick Start

1. Get an API key

Visit https://twitterapi.io/dashboard and obtain your x-api-key.

2. Cookies + proxy for write actions

create_tweet and delete_tweet authenticate with your account's own session cookies. From a browser logged into X, open DevTools → Application → Cookies → https://x.com and copy the auth_token and ct0 values.

Variable	Required	Description
TWITTERAPI_IO_KEY	always	twitterapi.io API key
TWITTERAPI_IO_AUTH_TOKEN	writes	auth_token cookie from a logged-in X session
TWITTERAPI_IO_CT0	writes	ct0 cookie from the same session
TWITTERAPI_IO_PROXY	writes	Residential proxy, http://user:pass@ip:port (required by the write endpoints)

The server derives the login_cookies value twitterapi.io expects from auth_token + ct0. These cookies expire over time (typically weeks); when a write starts returning an auth error, refresh them from the browser.

The API key alone is enough for the read tools. Add the cookie/proxy vars only if you need write actions.

3. Add to your MCP host

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "twitterapi": {
      "command": "npx",
      "args": ["-y", "@pedrot95dev/twitterapi.mcp"],
      "env": {
        "TWITTERAPI_IO_KEY": "your_key_here",
        "TWITTERAPI_IO_AUTH_TOKEN": "your_auth_token_cookie",
        "TWITTERAPI_IO_CT0": "your_ct0_cookie",
        "TWITTERAPI_IO_PROXY": "http://user:pass@ip:port"
      }
    }
  }
}

npx -y @pedrot95dev/twitterapi.mcp downloads and runs the latest published version. Only Node.js (>= 18) is required — no global install needed.

Other MCP hosts (e.g. Cursor): add the same npx command + env vars in the host's MCP settings UI or config file.

Tool: get_user_mentions

Fetch tweets that mention or reply to a user. Makes a single request per call; page by passing cursor from a previous response's next_cursor.

Parameter	Type	Default	Description
user_name	string	(required)	X username, with or without @
since_time	string	—	Start time filter (e.g. 2025-06-01 or ISO datetime)
until_time	string	—	End time filter
cursor	string	—	Pagination cursor from a previous next_cursor
query_type	"Latest" | "Relevance"	"Latest"	Sort mode
limit	integer	50	Max tweets to return from this single request

{
  "tweets": [ ... ],
  "count": 12,
  "has_next_page": true,
  "next_cursor": "DAADDAAB...",
  "status": "success",
  "msg": null
}

Tool: get_tweet_thread_context

Fetch the conversation thread around a tweet. Returns the original tweet, the intermediate replies up the chain, the tweet itself, and its direct replies. Each returned tweet includes entities.urls with expanded links — useful for scanning a mention's surrounding conversation for URLs.

Makes exactly one request per call (1-to-1 with the endpoint — no internal pagination). Page through longer threads with cursor.

Parameter	Type	Default	Description
tweet_id	string	(required)	The tweet ID to get the thread context for
cursor	string	—	Pagination cursor from a previous next_cursor

{
  "tweets": [ ... ],
  "count": 6,
  "has_next_page": false,
  "next_cursor": "",
  "status": "success",
  "msg": "success"
}

Note: this endpoint paginates unevenly — a page may return few or zero tweets while has_next_page is still true. Follow next_cursor until has_next_page is false to collect the whole thread.

Tool: create_tweet

Post a new tweet or reply. Supports quotes, media, communities, and scheduling. Requires the cookie + proxy env vars (see step 2).

Parameter	Type	Default	Description
tweet_text	string	(required)	The text content of the tweet
reply_to_tweet_id	string	—	Tweet ID to reply to (makes this a reply)
quote_tweet_id	string	—	Tweet ID to quote
attachment_url	string	—	URL for quote (alternative to quote_tweet_id)
community_id	string	—	Post inside a specific community
is_note_tweet	boolean	false	Allow >280 chars (Premium accounts)
media_ids	string[]	—	Media IDs from a prior /twitter/upload_media_v2
schedule_for	string	—	ISO-8601 future time, e.g. 2026-01-20T10:00:00.000Z

{ "tweet_id": "1234567890123456789", "status": "success", "msg": "success" }

Tool: delete_tweet

Delete one of your tweets by ID. Requires the cookie + proxy env vars.

Parameter	Type	Default	Description
tweet_id	string	(required)	The ID of the tweet to delete

{ "status": "success", "msg": "success" }

Contributing

Local development, build, and testing instructions are in CONTRIBUTING.md.

License

MIT — see LICENSE.

Credits

Based on the official twitterapi-io agent skill: https://github.com/kaitoInfra/twitterapi-io API service: https://twitterapi.io