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