# twitterapi.mcp

[![npm](https://img.shields.io/npm/v/@pedrot95dev/twitterapi.mcp)](https://www.npmjs.com/package/@pedrot95dev/twitterapi.mcp)

MCP server that exposes [twitterapi.io](https://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`](#tool-get_user_mentions) | Fetch tweets mentioning a user. | `GET /twitter/user/mentions` | API key |
| [`get_tweet_thread_context`](#tool-get_tweet_thread_context) | Fetch a page of the conversation thread around a tweet. | `GET /twitter/tweet/thread_context` | API key |
| [`create_tweet`](#tool-create_tweet) | Create a tweet or reply. | `POST /twitter/create_tweet_v2` | API key + cookies + proxy |
| [`delete_tweet`](#tool-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):

```json
{
  "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 |

```json
{
  "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` |

```json
{
  "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](#2-cookies--proxy-for-write-actions)).

| 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` |

```json
{ "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 |

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

## Contributing

Local development, build, and testing instructions are in [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT — see [LICENSE](LICENSE).

## Credits

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