Skip to main content
Glama
kaitoInfra

twitterapi-io-mcp-server

by kaitoInfra

twitterapi.io MCP Server

npm version MIT License MCP Spec 2025-11-25

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)

Related MCP server: X API FastMCP Server

Quick Start

1. Get an API key

Sign up at twitterapi.io — free tier available.

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):

{
  "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:

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

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:

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

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

MIT © twitterapi.io

Available Tools

12 tools
get_tweet_quotesA

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
tweetIdYesNumeric ID of the tweet to fetch quote-tweets for.
sinceTimeNoUnix timestamp (seconds) lower bound.
untilTimeNoUnix timestamp (seconds) upper bound.
includeRepliesNoInclude reply-type quote-tweets in addition to top-level. Default false.
cursorNoPagination cursor; omit for first page (~20 per page).

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses pagination behavior ('~20 per page') and time-bound support. However, it does not mention whether the tool is read-only, any authentication requirements, rate limits, or potential side effects. This is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences) and front-loaded with the core purpose. It conveys the essential information without fluff. Could be slightly more structured (e.g., bullet points), but it's efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters, no output schema, and no annotations, the description covers the core functionality, usage guidance, pagination, and time filters. It lacks details on return format or error handling, but it is reasonably complete for a fetch tool with good parameter descriptions in the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the cursor pagination ('~20 per page') and implying the use of sinceTime/untilTime for time bounds. However, it does not add significant meaning beyond what the schema already provides for each parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Fetch quote-tweets (tweets that quote the given tweetId).' It uses a specific verb ('Fetch') and resource ('quote-tweets'), and distinguishes from siblings like get_tweet_replies and get_tweet_retweeters by focusing on quote-tweets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: 'Useful for finding commentary on a tweet, measuring reach beyond direct replies.' It also mentions supported features (time bounds, pagination). However, it does not explicitly state when not to use it or suggest alternatives, which prevents a score of 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tweet_repliesA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
tweetIdYesNumeric ID of the tweet to fetch replies for.
cursorNoPagination cursor; omit for first page (~20 replies per page).
queryTypeNo'Latest' or 'Top' — sort order of replies. Default 'Latest'.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that it returns top-level replies (about 20 per page) with full tweet objects and uses pagination via cursor. It does not detail error handling or rate limits, but the core behavior is well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence is purposeful: first sentence defines purpose, second explains parameters and output, third lists use cases. No redundant information, front-loaded with key action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description sufficiently explains that it returns full tweet objects with pagination. It covers the main behavior and parameters, though it lacks detail on error scenarios or data structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds minimal extra value beyond the schema descriptions, repeating 'numeric tweetId' and 'omit cursor for first page' already present in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fetch replies to a specific tweet' with a specific verb and resource. It distinguishes from siblings like get_tweet_quotes and get_tweet_retweeters by focusing on replies and mentions use cases like thread analysis.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides concrete use cases (thread analysis, sentiment, building reply trees) and explains how to use the parameters (pass tweetId, cursor for pagination). It does not explicitly mention when not to use or alternatives, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tweet_retweetersA

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
tweetIdYesNumeric ID of the tweet to fetch retweeters for.
cursorNoPagination cursor; omit for first page (~100 per page).

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It discloses pagination via cursor with ~100 per page and states it returns user profiles with metadata. Could mention if authentication is needed or data freshness, but overall adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact with two sentences, no redundancy, and front-loads the purpose. Every sentence serves a clear function.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains what is returned (user profiles with metadata) and pagination behavior. Could be slightly more specific about the metadata fields, but sufficient for an agent to understand the tool's output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for tweetId and cursor. The description adds context by specifying page size (~100 per page) and clarifying the scope (simple retweets not quotes), which adds value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches retweeters for a specific tweet, distinguishing it from quote-tweets and mentioning it returns user profiles with metadata. It uses a specific verb and resource, and differentiates from sibling get_tweet_quotes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when not to use it (quote-tweets) and directs to get_tweet_quotes as alternative. It implies usage for simple retweets, but does not provide guidance on when to use over other siblings like get_tweet_replies.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tweets_by_idsA

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.

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

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the batch fetch nature, the input format (comma-separated string), and the batch size limit (up to 100 IDs). It does not mention error handling for invalid/deleted tweets but is sufficient for a simple read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: first states purpose, second gives usage guidance. It is concise with no wasted words and front-loads the key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description lists the types of data returned (author, text, engagement counts, media). It also covers the batch limit and input format, making the tool's behavior clear and complete for its simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds marginal value by repeating the comma-separated format and providing example IDs, but the schema already describes the parameter adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches full tweet objects by numeric IDs, specifying the exact resource (tweets) and action (batch-fetch). It distinguishes from siblings like search_tweets by emphasizing the use case when specific IDs are already known.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this when you already have specific tweet IDs' and gives examples of when this applies. It implies not to use when IDs are not available, but does not name alternative tools like search_tweets explicitly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_aboutA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
userNameYesTwitter/X screen name without @ — fetches the user's profile 'about' / bio page.

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the burden. It implies a read-only fetch but does not explicitly state behavioral traits like rate limits, safety, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no wasted words, front-loaded with the core purpose and immediate usage guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple fetch with one parameter, the description is adequate. It covers what, when, and alternatives, though it does not detail return fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the description adds value by clarifying the userName format (without @) and the purpose ('about' / bio page), going beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it fetches extended 'about' profile data by screen name and explicitly distinguishes it from get_user_info by noting it returns extra metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit guidance to use get_user_info first and only call this for additional fields, making the usage context and alternatives clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_followersA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
userNameYesTwitter/X screen name without @ — fetches followers of this user.
cursorNoPagination cursor from previous response's next_cursor. Omit for first page.
pageSizeNoFollowers per page (default 200, max 200). Each follower includes full profile metadata (name, bio, follower count, etc.).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses ordering (reverse chronological), metadata included, pagination via cursor, and limitation for large accounts. No annotations exist, so description carries full burden. Lacks specifics on rate limits, authentication, or error handling, but covers core behavior well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise 4-sentence description. Front-loaded with primary action, then ordering and metadata, then pagination and usage note. Every sentence adds value; no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, ordering, metadata, pagination, and large account handling. Lacks output schema details and error scenarios, but for a simple list tool with well-documented parameters, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds minor value (userName without @, cursor from previous response). Otherwise reinforces schema. No significant additional semantic depth.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Fetch followers of a Twitter/X user' with specific verb and resource. Distinguishes from siblings like get_user_followings, get_user_info. Provides usage context (analyze followers, build audiences, competitive analysis).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly mentions pagination for large accounts and that one call won't return all followers. Implies when to use (analyze followers) but lacks explicit when-not-to-use or comparison with sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_followingsA

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
userNameYesTwitter/X screen name without @ — fetches accounts this user follows.
cursorNoPagination cursor; omit for first page.
pageSizeNoFollowings per page (default 200, max 200). Each includes full profile metadata.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses pagination via cursor but omits other behavioral traits like authentication requirements, rate limits, or behavior for private accounts. The statement 'with full profile metadata' is vague.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with action, second sentence adds usage context. Every sentence is necessary and succinct.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters and no output schema, description covers core purpose, pagination, and a use case. Missing details on return format (what fields 'full profile metadata' includes) but adequate for basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, each parameter already well-documented. The description adds no new parameter-specific meaning beyond the schema; the 'interest graph' context is tangential to parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The verb 'Fetch' and resource 'accounts a user follows' clearly state the action. It includes 'with full profile metadata' to specify output. Distinguishes from siblings like get_user_followers (followers vs followings) and get_user_info (single user info).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use this to map a user's interest graph' with reasoning. Provides clear context but does not explicitly mention when not to use it or compare alternatives, though the context implies appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_infoA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
userNameYesTwitter/X screen name (handle) WITHOUT the leading @ sign. Example: 'elonmusk', not '@elonmusk'.

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as read-only nature, authentication requirements, rate limits, or any side effects. This is a gap for a potentially sensitive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first sentence covers action and input, second lists output and usage guidance. No wasted words, front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is complete. It specifies input format, lists all output fields, and gives usage guidance. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already has 100% coverage with a clear description of the userName parameter, including format and example. The tool description adds no additional parameter meaning, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches basic profile info by screen name, lists the return fields, and positions it as the starting point for user analysis, differentiating it from more specific sibling tools like get_user_followers.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly recommends using this tool as the starting point for any user analysis, providing clear context. However, it does not explicitly state when not to use it or list alternatives, though the sibling context implies differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_last_tweetsA

⚠️ 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).

ParametersJSON Schema
NameRequiredDescriptionDefault
userNameNoTwitter/X screen name without @ (e.g. 'elonmusk'). Provide EITHER userName OR userId.
userIdNoTwitter/X numeric user ID (e.g. '44196397'). Provide EITHER userName OR userId. Prefer userId if known — handles can change.
cursorNoPagination cursor; omit for first page.
includeRepliesNoInclude the user's reply tweets in addition to top-level tweets. Default false — only top-level tweets.

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description discloses key behaviors: sorting order, pagination (~20 per page, cursor-based), default for includeReplies, and the mutual exclusivity of userName/userId. This fully compensates for missing annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently written with a warning first, then core functionality, then specific parameter guidance. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters, no annotations, and no output schema, the description provides all necessary information for selection and correct invocation: purpose, usage constraints, parameter behavior, pagination, and defaults. No gaps are evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds critical context: mutual exclusivity of userName/userId, cursor usage for pagination, and default behavior for includeReplies. This enhances understanding beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches the most recent tweets for a user, sorted by created_at descending. It explicitly contrasts with date-range queries and directs to a sibling tool search_tweets, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use (latest/recent queries) and when-not-to-use (date-range queries) with a concrete alternative and example. Also advises preferring userId over userName, aiding correct invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_user_mentionsA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
userNameYesTwitter/X screen name without @ — fetches tweets that mention this user (@userName).
sinceTimeNoUnix timestamp (seconds) lower bound — only mentions after this time. Omit for no lower bound.
untilTimeNoUnix timestamp (seconds) upper bound. Omit for no upper bound.
cursorNoPagination cursor; omit for first page (~20 per page).

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses pagination via cursor and time bounds, but lacks information on rate limits, authentication requirements, or behavior when a user does not exist. This is adequate but leaves some behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with three sentences. The first sentence states the core purpose, the second adds use cases, and the third covers technical details (time and pagination). No superfluous content; it is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (4 parameters, no output schema, no nested objects), the description is reasonably complete. It covers purpose, use cases, and parameter mechanics. However, it does not describe the return format or error handling, which would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds minor context to parameters (e.g., 'Unix seconds' for times, 'without @' for userName) but does not significantly enhance understanding beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Fetch tweets that mention a specific Twitter/X user.' It uses a specific verb ('Fetch') and resource ('tweets mentioning a user'), and provides concrete use cases like brand monitoring and sentiment tracking. This effectively distinguishes it from sibling tools such as search_tweets or get_user_last_tweets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool, citing brand monitoring and conversation tracking. It mentions time-bound queries and pagination, which are useful hints. However, it does not explicitly state when not to use it or mention alternatives like search_tweets for broader searches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_tweetsA

🎯 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesTwitter 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'
queryTypeYes'Latest' returns most recent tweets first; 'Top' returns highest-engagement tweets first. Default to 'Latest' for time-sensitive queries.
cursorNoPagination cursor from a previous response's next_cursor field. Omit for first page. Each page returns ~20 tweets.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full burden. It discloses key behaviors: returns ~20 tweets per page, reverse chronological order by default, supports advanced search syntax, exclusive 'until:', and pagination via cursor. It lacks details on rate limits or authentication, but these are acceptable for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is longer than minimal but well-structured and front-loaded with the primary use case and key instructions. Every sentence adds value, with examples being helpful rather than verbose. Minor improvement could be trimming some redundant examples.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (advanced search syntax, pagination, sort types), the description is very complete. It covers edge cases like exclusive 'until:', pagination usage, and result count per page. No output schema exists, but the description implies response structure with next_cursor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds substantial meaning beyond the schema: it provides concrete examples, date format specification, note about 'until:' being exclusive, and guidance on when to use 'Latest' vs 'Top'. This greatly aids correct usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is the primary choice for date-range, historical, and keyword-based tweet queries, with specific verb 'search Twitter/X for tweets matching a query'. It distinguishes from sibling tool get_user_last_tweets by specifying different use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly marks itself as 'PRIMARY CHOICE' and provides explicit guidance on when to use this tool versus get_user_last_tweets. It includes detailed usage examples for various scenarios (date ranges, keywords, etc.) and explains formatting.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 12 tool updatesv0.2.0
    • First observedget_trends
    • First observedget_tweet_quotes
    • First observedget_tweet_replies
    • First observedget_tweet_retweeters
    • First observedget_tweets_by_ids
    • First observedget_user_about
    • First observedget_user_followers
    • First observedget_user_followings
    • First observedget_user_info
    • First observedget_user_last_tweets
    • First observedget_user_mentions
    • First observedsearch_tweets

TDQS

A4.3/5.0
Disambiguation5/5

Each tool targets a distinct entity and action: trends, tweet interactions (quotes, replies, retweeters, batch fetch), user details (info, about, followers, followings, last tweets, mentions), and search. Descriptions explicitly clarify boundaries, e.g., get_user_last_tweets vs. search_tweets for date queries.

Naming Consistency5/5

All tools follow the verb_noun pattern with prefixes 'get_' or 'search_'. The naming is predictable and clear: get_<entity>_<detail> for most, with search_tweets as a minor but acceptable variation.

Tool Count5/5

12 tools cover a comprehensive set of Twitter read operations without excess. The count is well-balanced, each tool serves a clear purpose, and the scope fits a focused Twitter data retrieval server.

Completeness4/5

The surface covers essential read operations: trends, tweet data, user profiles, followers/followings, mentions, and search. Minor gaps exist (e.g., no dedicated single tweet fetch or reply threading), but workarounds like get_tweets_by_ids and get_tweet_replies suffice.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Model Context Protocol server that enables programmatic interaction with Twitter API, allowing users to post tweets, search for content, and retrieve user timelines through standardized MCP tools.
    19
    MIT
  • F
    license
    Not graded
    quality
    F
    maintenance
    A local MCP server that exposes the X API (formerly Twitter API) as tools, enabling operations like posting, searching, user management, and more via natural language commands.
    853
    -
  • A
    license
    A
    quality
    F
    maintenance
    A Model Context Protocol (MCP) server that provides access to Twitter data through the TwitterAPI.io service, enabling Claude and other MCP clients to interact with Twitter's ecosystem without requiring Twitter developer account approval.
    11
    15
    4
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kaitoInfra/twitterapi-io-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server