io.github.pedrot95dev/twitterapi
Read/write X (Twitter) via twitterapi.io: mentions, thread context, create and delete tweets.
Open source Open in the app JSON README (API)
About
Read/write X (Twitter) via twitterapi.io: mentions, thread context, create and delete tweets.
Details
- Kind
- MCP servers
- Topic
- Social & content
- Publisher
- pedrot95dev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Last push
- 2026-07-03T13:29:54Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 04:01:00
- Updated
- 2026-08-29 04:01:00
- Origin id
io.github.pedrot95dev/twitterapi
README
# 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