io.twitterapi/mcp-server

Official12 toolsLive

by kaitoInfra · TypeScript

Official twitterapi.io hosted MCP: Twitter/X tweets, users, followers, trends. OAuth or API key.

io.twitterapi/mcp-server (Model Context Protocol)

The io.twitterapi/mcp-server is an Official twitterapi.io hosted MCP server that provides access to Twitter/X data. It supports retrieving tweets, user details, followers information, and trends. Authentication is available via OAuth or an API key.

🛠️ Key Features

Twitter/X tweets
User information
Followers data
Trends

🚀 Use Cases

Fetch tweets for a given account or context
Inspect user profiles
Analyze follower relationships
Retrieve current trends

⚡ Developer Benefits

MCP integration for Twitter/X datasets
Supports OAuth and API key authentication

⚠️ Limitations

Scope is limited to Twitter/X tweets, users, followers, and trends

Topics

ai-agentanthropicclaudemcpmcp-servermodel-context-protocoltwittertwitter-apix-api

Captured live from the server via tools/list.

search_tweets

🎯 PRIMARY CHOICE for date-range / historical / keyword-based tweet queries. Use this (NOT get_user_last_tweets) whenever user asks about a SPECIFIC TIME RANGE or historical tweets: • 'tweets from January 2026' → query='from:elonmusk since:2026-01-01 until:2026-02-01' • 'tweets between X and Y' → 'from:USER since:X until:Y' • 'tweets last week / last month' → translate to since:/until: dates • 'tweets containing keyword X by user Y' → 'from:Y X' • 'older tweets' / 'archive' / 'in 2025' → use date range, not pagination Date format: YYYY-MM-DD (UTC midnight). 'until:' is exclusive (until:2026-02-01 = up to Jan 31). General: Search Twitter/X for tweets matching a query. Supports the full Twitter advanced search syntax (from:, to:, since:, until:, lang:, filter:, has:, -, OR, etc). Returns ~20 tweets per page in reverse chronological order ('Latest') or by engagement ('Top'). Use this for keyword research, monitoring mentions of a brand/topic, finding tweets in a date range, or any open-ended tweet discovery.

Parameters3

query	string	required	Twitter advanced search query string. Supports operators: from:USER, to:USER, since:YYYY-MM-DD, until:YYYY-MM-DD, lang:en, filter:replies, -filter:retweets, has:images, etc. Example: 'from:elonmusk since:2026-01-01 has:images'
queryType	string	required	'Latest' returns most recent tweets first; 'Top' returns highest-engagement tweets first. Default to 'Latest' for time-sensitive queries.
cursor	string	optional	Pagination cursor from a previous response's next_cursor field. Omit for first page. Each page returns ~20 tweets.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Twitter advanced search query string. Supports operators: from:USER, to:USER, since:YYYY-MM-DD, until:YYYY-MM-DD, lang:en, filter:replies, -filter:retweets, has:images, etc. Example: 'from:elonmusk since:2026-01-01 has:images'"
    },
    "queryType": {
      "type": "string",
      "enum": [
        "Latest",
        "Top"
      ],
      "description": "'Latest' returns most recent tweets first; 'Top' returns highest-engagement tweets first. Default to 'Latest' for time-sensitive queries."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from a previous response's next_cursor field. Omit for first page. Each page returns ~20 tweets."
    }
  },
  "required": [
    "query",
    "queryType"
  ]
}

get_user_info

Fetch basic profile info for a Twitter/X user by their screen name (handle). Returns user ID, display name, bio, follower/following counts, verified status, profile picture, banner, location, website, and account creation date. Use this as the starting point for any user analysis.

Parameters1

userName

string

required

Twitter/X screen name (handle) WITHOUT the leading @ sign. Example: 'elonmusk', not '@elonmusk'.

Raw schema

{
  "type": "object",
  "properties": {
    "userName": {
      "type": "string",
      "description": "Twitter/X screen name (handle) WITHOUT the leading @ sign. Example: 'elonmusk', not '@elonmusk'."
    }
  },
  "required": [
    "userName"
  ]
}

get_user_about

Fetch the extended 'about' / profile page data for a Twitter/X user by screen name. Returns extra profile metadata beyond what get_user_info gives (when available). Use get_user_info first; only call this if you need additional about-page fields.

Parameters1

userName

string

required

Twitter/X screen name without @ — fetches the user's profile 'about' / bio page.

Raw schema

{
  "type": "object",
  "properties": {
    "userName": {
      "type": "string",
      "description": "Twitter/X screen name without @ — fetches the user's profile 'about' / bio page."
    }
  },
  "required": [
    "userName"
  ]
}

get_user_followers

Fetch followers of a Twitter/X user in reverse chronological order (newest first), each with full profile metadata (name, bio, follower count, verified status, etc.). Paginates via cursor. Use this to analyze who follows an account, build follower audiences, or sample for competitive analysis. For large accounts use pagination; you will not get all followers in one call.

Parameters3

userName	string	required	Twitter/X screen name without @ — fetches followers of this user.
cursor	string	optional	Pagination cursor from previous response's next_cursor. Omit for first page.
pageSize	integer	optional	Followers per page (default 200, max 200). Each follower includes full profile metadata (name, bio, follower count, etc.).

Raw schema

{
  "type": "object",
  "properties": {
    "userName": {
      "type": "string",
      "description": "Twitter/X screen name without @ — fetches followers of this user."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from previous response's next_cursor. Omit for first page."
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Followers per page (default 200, max 200). Each follower includes full profile metadata (name, bio, follower count, etc.)."
    }
  },
  "required": [
    "userName"
  ]
}

get_user_followings

Fetch the accounts a Twitter/X user follows, with full profile metadata. Paginates via cursor. Use this to map a user's interest graph (who they follow signals what they care about).

Parameters3

userName	string	required	Twitter/X screen name without @ — fetches accounts this user follows.
cursor	string	optional	Pagination cursor; omit for first page.
pageSize	integer	optional	Followings per page (default 200, max 200). Each includes full profile metadata.

Raw schema

{
  "type": "object",
  "properties": {
    "userName": {
      "type": "string",
      "description": "Twitter/X screen name without @ — fetches accounts this user follows."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor; omit for first page."
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "description": "Followings per page (default 200, max 200). Each includes full profile metadata."
    }
  },
  "required": [
    "userName"
  ]
}

get_user_last_tweets

⚠️ ONLY for 'latest / recent / what's new' queries about a user. DO NOT use for date-range queries (e.g. 'tweets from January 2026', 'tweets last week', 'tweets between X and Y', 'tweets in 2025'). For specific dates / older tweets, use **search_tweets** with query like 'from:elonmusk since:2026-01-01 until:2026-02-01'. Fetch the MOST RECENT tweets posted by a Twitter/X user, sorted by created_at descending (newest first). Provide EITHER userName (screen name, no @) OR userId (numeric). Use userId when known — handles can change. Set includeReplies=true to include the user's reply tweets in addition to top-level tweets. Paginates via cursor (~20 per page).

Parameters4

userName	string	optional	Twitter/X screen name without @ (e.g. 'elonmusk'). Provide EITHER userName OR userId.
userId	string	optional	Twitter/X numeric user ID (e.g. '44196397'). Provide EITHER userName OR userId. Prefer userId if known — handles can change.
cursor	string	optional	Pagination cursor; omit for first page.
includeReplies	boolean	optional	Include the user's reply tweets in addition to top-level tweets. Default false — only top-level tweets.

Raw schema

{
  "type": "object",
  "properties": {
    "userName": {
      "type": "string",
      "description": "Twitter/X screen name without @ (e.g. 'elonmusk'). Provide EITHER userName OR userId."
    },
    "userId": {
      "type": "string",
      "description": "Twitter/X numeric user ID (e.g. '44196397'). Provide EITHER userName OR userId. Prefer userId if known — handles can change."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor; omit for first page."
    },
    "includeReplies": {
      "type": "boolean",
      "description": "Include the user's reply tweets in addition to top-level tweets. Default false — only top-level tweets."
    }
  }
}

get_user_mentions

Fetch tweets that mention a specific Twitter/X user (i.e. tweets containing @userName). Useful for brand monitoring, sentiment tracking on a public figure, or finding conversations involving an account. Supports time-bound queries via sinceTime/untilTime (Unix seconds). Paginates via cursor.

Parameters4

userName	string	required	Twitter/X screen name without @ — fetches tweets that mention this user (@userName).
sinceTime	integer	optional	Unix timestamp (seconds) lower bound — only mentions after this time. Omit for no lower bound.
untilTime	integer	optional	Unix timestamp (seconds) upper bound. Omit for no upper bound.
cursor	string	optional	Pagination cursor; omit for first page (~20 per page).

Raw schema

{
  "type": "object",
  "properties": {
    "userName": {
      "type": "string",
      "description": "Twitter/X screen name without @ — fetches tweets that mention this user (@userName)."
    },
    "sinceTime": {
      "type": "integer",
      "description": "Unix timestamp (seconds) lower bound — only mentions after this time. Omit for no lower bound."
    },
    "untilTime": {
      "type": "integer",
      "description": "Unix timestamp (seconds) upper bound. Omit for no upper bound."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor; omit for first page (~20 per page)."
    }
  },
  "required": [
    "userName"
  ]
}

get_tweets_by_ids

Batch-fetch full tweet objects by their numeric tweet IDs. Pass a comma-separated string of up to 100 IDs. Use this when you already have specific tweet IDs (e.g., from a search result, a URL, or a webhook event) and need the full tweet data — author, text, engagement counts, media, etc.

Parameters1

tweet_ids

string

required

Comma-separated tweet IDs (e.g. '1234567890,9876543210'). Batch fetch up to 100 tweets in one call. Tweet IDs are numeric strings.

Raw schema

{
  "type": "object",
  "properties": {
    "tweet_ids": {
      "type": "string",
      "description": "Comma-separated tweet IDs (e.g. '1234567890,9876543210'). Batch fetch up to 100 tweets in one call. Tweet IDs are numeric strings."
    }
  },
  "required": [
    "tweet_ids"
  ]
}

get_tweet_replies

Fetch replies to a specific tweet. Pass the numeric tweetId of the root tweet; returns top-level replies (about 20 per page) with full tweet objects. Use this for thread analysis, sentiment on a viral post, or building reply trees.

Parameters3

tweetId	string	required	Numeric ID of the tweet to fetch replies for.
cursor	string	optional	Pagination cursor; omit for first page (~20 replies per page).
queryType	string	optional	'Latest' or 'Top' — sort order of replies. Default 'Latest'.

Raw schema

{
  "type": "object",
  "properties": {
    "tweetId": {
      "type": "string",
      "description": "Numeric ID of the tweet to fetch replies for."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor; omit for first page (~20 replies per page)."
    },
    "queryType": {
      "type": "string",
      "enum": [
        "Latest",
        "Top"
      ],
      "description": "'Latest' or 'Top' — sort order of replies. Default 'Latest'."
    }
  },
  "required": [
    "tweetId"
  ]
}

get_tweet_quotes

Fetch quote-tweets (tweets that quote the given tweetId). Useful for finding commentary on a tweet, measuring reach beyond direct replies. Supports time bounds (sinceTime/untilTime, Unix seconds). Paginates via cursor (~20 per page).

Parameters5

tweetId	string	required	Numeric ID of the tweet to fetch quote-tweets for.
sinceTime	integer	optional	Unix timestamp (seconds) lower bound.
untilTime	integer	optional	Unix timestamp (seconds) upper bound.
includeReplies	boolean	optional	Include reply-type quote-tweets in addition to top-level. Default false.
cursor	string	optional	Pagination cursor; omit for first page (~20 per page).

Raw schema

{
  "type": "object",
  "properties": {
    "tweetId": {
      "type": "string",
      "description": "Numeric ID of the tweet to fetch quote-tweets for."
    },
    "sinceTime": {
      "type": "integer",
      "description": "Unix timestamp (seconds) lower bound."
    },
    "untilTime": {
      "type": "integer",
      "description": "Unix timestamp (seconds) upper bound."
    },
    "includeReplies": {
      "type": "boolean",
      "description": "Include reply-type quote-tweets in addition to top-level. Default false."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor; omit for first page (~20 per page)."
    }
  },
  "required": [
    "tweetId"
  ]
}

get_tweet_retweeters

Fetch users who retweeted a specific tweet (the simple 'retweet' action, not quote-tweets — for those use get_tweet_quotes). Returns user profiles with metadata. Paginates via cursor (~100 per page).

Parameters2

tweetId	string	required	Numeric ID of the tweet to fetch retweeters for.
cursor	string	optional	Pagination cursor; omit for first page (~100 per page).

Raw schema

{
  "type": "object",
  "properties": {
    "tweetId": {
      "type": "string",
      "description": "Numeric ID of the tweet to fetch retweeters for."
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor; omit for first page (~100 per page)."
    }
  },
  "required": [
    "tweetId"
  ]
}

get_trends

Fetch current trending topics/hashtags for a location. Pass a Yahoo Where-On-Earth ID (woeid). Common: 1=Worldwide, 23424977=USA, 23424975=UK, 23424856=Japan, 23424848=India, 23424881=South Korea. Use woeid=1 for global trends if you don't know a specific location.

Parameters2

woeid	integer	required	Yahoo Where-On-Earth ID for the location. Common values: 1 = Worldwide, 23424977 = USA, 23424975 = UK, 23424856 = Japan. Use 1 for global trends if unsure.
count	integer	optional	Max trends to return (default API behavior; may be silently capped by API).

Raw schema

{
  "type": "object",
  "properties": {
    "woeid": {
      "type": "integer",
      "description": "Yahoo Where-On-Earth ID for the location. Common values: 1 = Worldwide, 23424977 = USA, 23424975 = UK, 23424856 = Japan. Use 1 for global trends if unsure."
    },
    "count": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Max trends to return (default API behavior; may be silently capped by API)."
    }
  },
  "required": [
    "woeid"
  ]
}

README.md5 KBView on GitHub

twitterapi.io MCP Server

Official Model Context Protocol server for twitterapi.io — Twitter / X data API for AI agents and applications.

Connect Claude Desktop, Cursor, VS Code Copilot, or any MCP client to twitterapi.io and search tweets, fetch user profiles, get followers, replies, trends, and more — all from natural language.

Features

12 read-only tools mapped 1:1 to twitterapi.io's verified production endpoints:

Tool	What it does
`search_tweets`	Advanced search with Twitter operators (`from:`, `since:`, `lang:`, `has:`, …)
`get_user_info`	User profile basics by screen name
`get_user_about`	Extended profile / about page
`get_user_followers`	Followers with full profile metadata (paginated)
`get_user_followings`	Following list with profile metadata (paginated)
`get_user_last_tweets`	A user's recent tweets (timeline)
`get_user_mentions`	Tweets that mention a user
`get_tweets_by_ids`	Batch fetch tweets by ID (up to 100)
`get_tweet_replies`	Replies to a tweet
`get_tweet_quotes`	Quote-tweets of a tweet
`get_tweet_retweeters`	Users who retweeted a tweet
`get_trends`	Trending topics by location (WOEID)

Quick Start

1. Get an API key

2. Configure your MCP client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json

{
  "mcpServers": {
    "twitterapi-io": {
      "command": "npx",
      "args": ["-y", "@twitterapi_io/mcp-server"],
      "env": {
        "TWITTERAPI_IO_API_KEY": "your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The 12 tools will be available in any chat — Claude will pick the right one based on your prompt.

Cursor

Open Settings → MCP → Add new MCP Server:

json

{
  "mcpServers": {
    "twitterapi-io": {
      "command": "npx",
      "args": ["-y", "@twitterapi_io/mcp-server"],
      "env": {
        "TWITTERAPI_IO_API_KEY": "your_key_here"
      }
    }
  }
}

VS Code (Copilot Chat with MCP)

Add to your MCP servers config — same shape as Claude Desktop / Cursor.

Claude Code

bash

claude mcp add twitterapi-io npx -- -y @twitterapi_io/mcp-server -e TWITTERAPI_IO_API_KEY=your_key_here

3. Use it

In any MCP-enabled chat:

"Find recent tweets from @elonmusk about AI in the last week"

"Get the follower list of @sama and show me the top 20 by follower count"

"What are the current trending topics in Japan?"

Claude (or your client) will automatically pick search_tweets / get_user_followers / get_trends and call them with the right parameters.

Authentication

Authentication is via the TWITTERAPI_IO_API_KEY environment variable, injected by your MCP client. The server never stores or logs the key. Each tool call sends the key in the X-API-Key header to https://api.twitterapi.io.

Pagination

Tools that return lists (followers, replies, search results, etc.) return a next_cursor field. Pass it back as the cursor argument on the next call to page through. Each page is typically ~20 items.

Error handling

429 / 5xx responses are automatically retried with exponential backoff (3 attempts, 1s/2s/4s)
Network timeouts: 30s per request
4xx errors (other than 429) surface immediately to the LLM with the original message

Tools — full spec

Each tool's input schema is exposed via MCP's tools/list and follows JSON Schema. Run npx @twitterapi_io/mcp-server with mcp-inspector to browse interactively:

bash

npx @modelcontextprotocol/inspector npx -y @twitterapi_io/mcp-server

What's NOT included

By design, this server exposes read-only endpoints. The following are intentionally excluded to keep the server safe for autonomous agent use:

❌ Posting tweets, likes, retweets, follows, DMs
❌ Account login / 2FA
❌ Profile / banner / avatar editing
❌ Media upload
❌ Account deletion
❌ Realtime stream / webhook setup (does not fit the MCP request/response model)

These features are available in the full twitterapi.io REST API — use it directly if you need write access.

Spec compliance

Built on @modelcontextprotocol/sdk v1
Targets MCP spec 2025-11-25 (latest)
Transport: stdio (Streamable HTTP planned for v0.2+ for remote/hosted use)
Tested with: mcp-inspector, Claude Desktop, Cursor, Claude Code

Development

bash

git clone https://github.com/kaitoInfra/twitterapi-io-mcp-server.git
cd twitterapi-io-mcp-server
npm install
npm run build
TWITTERAPI_IO_API_KEY=xxx npm run inspect  # opens mcp-inspector

License

Install

Tools (12)

search_tweetsget_user_infoget_user_aboutget_user_followersget_user_followingsget_user_last_tweetsget_user_mentionsget_tweets_by_ids

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.twitterapi.io/v1/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.twitterapi.io/v1/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

io.twitterapi/mcp-server

io.twitterapi/mcp-server (Model Context Protocol)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

search_tweets

get_user_info

get_user_about

get_user_followers

get_user_followings

get_user_last_tweets

get_user_mentions

get_tweets_by_ids

get_tweet_replies

get_tweet_quotes

get_tweet_retweeters

get_trends

twitterapi.io MCP Server

Features

Quick Start

1. Get an API key

2. Configure your MCP client

Claude Desktop

Cursor

VS Code (Copilot Chat with MCP)

Claude Code

3. Use it

Authentication

Error handling

Tools — full spec

What's NOT included

Spec compliance

Development

Links

License

Install

Remote endpoint

Related servers