twitterapis-mcp

# @twitterapis/mcp

[![npm version](https://img.shields.io/npm/v/@twitterapis/mcp)](https://www.npmjs.com/package/@twitterapis/mcp)
[![npm downloads](https://img.shields.io/npm/dm/@twitterapis/mcp)](https://www.npmjs.com/package/@twitterapis/mcp)
[![license](https://img.shields.io/npm/l/@twitterapis/mcp)](./LICENSE)

Official **Model Context Protocol** server for [twitterapis.com](https://www.twitterapis.com), the Twitter / X API as native tools for Claude, Cursor, Windsurf, and any MCP client. Reads (search, profiles, timelines, followers, DMs) plus write actions (post, like, retweet, follow).

Ask your agent to search tweets, pull a user's profile or timeline, list followers/following, fetch thread context, or enumerate list members and it calls the API directly. Every tool maps to a REST endpoint at `https://api.twitterapis.com`; the server holds no state and forwards your API key on each call.

## Quick start

No install needed. Run with `npx`. You need one thing: an API key (free $0.50 in credits, no card required): **[twitterapis.com/signup](https://www.twitterapis.com/signup)**.

## Setup

### Claude Desktop

Edit `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "twitterapis": {
      "command": "npx",
      "args": ["-y", "@twitterapis/mcp@latest"],
      "env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
    }
  }
}
```

Restart Claude Desktop. The `twitter_*` tools appear in the tool picker.

### Cursor

`~/.cursor/mcp.json` (or Settings → MCP → Add New Server):

```json
{
  "mcpServers": {
    "twitterapis": {
      "command": "npx",
      "args": ["-y", "@twitterapis/mcp@latest"],
      "env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
    }
  }
}
```

### Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "twitterapis": {
      "command": "npx",
      "args": ["-y", "@twitterapis/mcp@latest"],
      "env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
    }
  }
}
```

### VS Code (Copilot / agent mode)

`.vscode/mcp.json` in your workspace, or the user-level MCP settings:

```json
{
  "servers": {
    "twitterapis": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@twitterapis/mcp@latest"],
      "env": { "TWITTERAPIS_KEY": "YOUR_API_KEY" }
    }
  }
}
```

## Configuration

| Env var | Required | Default | Purpose |
|---|---|---|---|
| `TWITTERAPIS_KEY` | Yes | (none) | API key from [dashboard](https://www.twitterapis.com/dashboard) |
| `TWITTERAPIS_BASE_URL` | No | `https://api.twitterapis.com` | Override the API host |
| `TWITTERAPIS_TIMEOUT_MS` | No | `30000` | Per-request timeout in milliseconds |

## Tools

112 tools: 68 reads and 44 write actions. Most user endpoints accept `username` (handle without @) **or** `user_id` (`twitter_user_likes` and `twitter_user_tweets_complete` require `user_id`); tweet endpoints accept `id` **or** `url`; paginated endpoints return a `cursor` you pass back to get the next page. Every data read (except `twitter_audience_summary`, which always returns its full summary) also takes `fields` (comma-separated dotted paths to keep, e.g. `id,text,author.username`; pagination and envelope keys always survive) and `compact` (`"1"` for a built-in preset of ids, text, counts and author basics), so a model paying per token can trim a page to what it will read. Four of the reads are free account lookups (`twitter_account_me`, `twitter_account_payments`, `twitter_feedback_get`, `twitter_feedback_list`); the 14 monitoring tools and `twitter_feedback_send` are also free (account administration, not metered reads).

Public reads (search, profiles, tweets, followers, likes) work with just your API key. The **account-only** reads (bookmarks, DMs, home timeline, followers-you-know) and **most write actions** act AS an authenticated X account, so they need a session linked to your key first (returns HTTP 409 until then). Link a session either by registering your x.com cookies (`twitter_customer_session`) or by logging in with a username/password (`twitter_user_login`). Alternatively, pass **per-call inline credentials** on any of those tools (`auth_token` + `ct0`, with optional `proxy_url` / `user_agent`) to act AS that account for a single call without pre-registering a session, so one API key can act as many accounts. For write actions, set `proxy_url` to a residential proxy, since X soft-blocks writes that egress from datacenter IPs. Each write tool is annotated `readOnlyHint: false`; reversing actions (delete, unfollow, unlike, unretweet, unbookmark, monitor/webhook delete) are annotated `destructiveHint: true` so MCP clients can prompt before running them. The **monitoring** and **feedback** tools (see below) are the exception: they administer your twitterapis.com account, not an X session, so they need only your API key, no linked session and no inline credentials.

### Reads

| Tool | What it does |
|---|---|
| `twitter_advanced_search` | Search tweets with X operators (`from:`, `min_faves:`, `since:`, `filter:links`, etc.) |
| `twitter_user_search` | Find user accounts by name or keyword |
| `twitter_user_info` | Full profile by handle (bio, counts, verification, location) |
| `twitter_user_info_by_id` | Full profile by numeric user id |
| `twitter_user_status` | Is an account alive, suspended, or deleted |
| `twitter_user_about` | A user's structured About object (category, professional/business labels, verification + identity-verification flags, joined date, and X's 'About this account' transparency panel) |
| `twitter_user_about_batch` | The same About object for up to 100 accounts in one call (usernames or user_ids), billed per account answered; for vetting a list by country or account history |
| `twitter_audience_summary` | Who an audience is: a country histogram and likely-bot share over a sample of up to 100 followers or retweeters |
| `twitter_user_affiliates` | Accounts affiliated with an organization profile |
| `twitter_check_follow_relationship` | Follow relationship between two accounts, by id or username (who follows whom) |
| `twitter_check_follow_relationship_batch` | One account against up to 100 others in one call, either direction (which of these accounts follow the brand) |
| `twitter_user_tweets` | A user's recent original tweets (replies excluded) |
| `twitter_user_tweets_and_replies` | A user's full timeline (tweets + replies) |
| `twitter_user_tweets_complete` | A large batch of a user's tweet history per call (see [paging note](#paging-twitter_user_tweets_complete)) |
| `twitter_user_media` | Images and videos a user has posted |
| `twitter_user_mentions` | Recent public tweets mentioning a user |
| `twitter_user_likes` | Tweets a user has liked (public Likes tab) |
| `twitter_user_followers` | Accounts that follow a user |
| `twitter_user_following` | Accounts a user follows |
| `twitter_user_followers_v2` | Followers with the v2 response shape (richer fields, deeper cursoring) |
| `twitter_user_following_v2` | Following with the v2 response shape (richer fields, deeper cursoring) |
| `twitter_user_verified_followers` | A user's verified followers only |
| `twitter_followers_you_know` | Followers of a target that your authenticated account also follows |
| `twitter_tweet_detail` | Single tweet: text, author, metrics, media, quoted/reply context |
| `twitter_tweet_replies` | Replies to a tweet |
| `twitter_tweet_thread` | Full author thread (connected tweet chain by same author) |
| `twitter_tweet_retweeters` | Accounts that retweeted a tweet |
| `twitter_tweet_quotes` | Tweets that quote a tweet, with their text. Search-backed, so `count` is what search returned, not the tweet's true `quote_count` |
| `twitter_list_members` | Members of a Twitter/X List |
| `twitter_list_followers` | Accounts that follow a public List (a different set from its members) |
| `twitter_list_tweets` | Posts by a List's members, search-backed: filterable by `since` / `until` date, `include_replies`, and `product` (Latest / Top), no retweets |
| `twitter_list_timeline` | A List's native X feed: retweets and X's own ordering included, no filters, paging only |
| `twitter_home_timeline` | Your authenticated account's Home timeline _(session)_ |
| `twitter_bookmarks` | Your authenticated account's bookmarks _(session)_ |
| `twitter_blocking` | Accounts your authenticated account has blocked (your own list only) _(session)_ |
| `twitter_muting` | Accounts your authenticated account has muted (your own list only) _(session)_ |
| `twitter_bookmark_search` | Full-text search within your bookmarks _(session)_ |
| `twitter_bookmark_folders` | Your authenticated account's bookmark folders _(session)_ |
| `twitter_bookmark_folder_timeline` | Tweets inside one of your bookmark folders, by `folder_id` _(session)_ |
| `twitter_dm_list` | Your DM conversations (inbox), read-only _(session)_ |
| `twitter_dm_conversation` | Messages in one DM conversation, read-only; pass the previous page's `min_entry_id` as `max_id` to page back _(session)_ |
| `twitter_spaces_info` | Metadata and participant roster for one X Space, live or ended (by Space `id`) |
| `twitter_community_search` | Find X Communities by keyword; the discovery step that produces the numeric id the rest of the community family needs |
| `twitter_community_info` | One X Community by numeric id: name, counts, join policy, rules, topic, banners, admin |
| `twitter_community_about` | A community's moderators and a member preview, each returned as a full user profile, not the reduced row `_members`/`_moderators` return |
| `twitter_community_members` | A community's member roster, each row carrying that member's `Admin` / `Moderator` / `Member` role |
| `twitter_community_moderators` | A community's moderators and admins, from its own upstream operation (not a filter over the roster) |
| `twitter_community_tweets` | A community's post timeline, with the pinned post returned as its own `pinned` field |
| `twitter_community_memberships` | The inv