Skip to main content
Glama

Twitter/X Search

twitter
Read-onlyIdempotent

PURPOSE: Direct Twitter/X access — raw operations on a specific account, tweet, search, list, or community.

COVERS (by action): tweet search & user search; a named user's profile / tweets / timeline / mentions; followers, followings & follow checks; a tweet's replies / thread / quotes / retweeters; trends; community & list timelines; spaces; long-form articles.

BOUNDARIES:

  • Use twitter for RAW ops on a NAMED account or a specific tweet. For "what are KOLs calling / 喊单" use signal(kol_call); for general crypto/news tweet CONTENT use news(sources=["twitter"]).

USAGE — pick an action and supply its required params:

  • search: query (+ optional query_type, cursor, time_range)

  • user_info / user_about: user_name

  • batch_user_info: user_ids (comma-separated)

  • search_users: query

  • user_tweets: user_name or user_id (+ optional include_replies, cursor)

  • user_timeline: user_id (+ optional cursor)

  • user_mentions: user_name (+ optional cursor)

  • followers / followings: user_name (+ optional cursor)

  • verified_followers: user_id (+ optional cursor)

  • check_follow: user_name + target_user_name

  • tweets_by_ids: tweet_ids (comma-separated)

  • tweet_replies / tweet_replies_v2 / tweet_thread / tweet_quotes / tweet_retweeters: tweet_id (+ optional cursor)

  • trends: woeid (default 1 = worldwide)

  • community_tweets: community_id (+ optional cursor)

  • article: tweet_id

  • space_detail: space_id

  • list_tweets / list_timeline: list_id (+ optional cursor)

RETURNS: the raw twitterapi.io payload for the chosen action (tweets / users / relationships / trends), paginated via next_cursor.

EXAMPLES:

  • "搜 BTC 相关推文" → action="search", query="BTC"

  • "Elon Musk 账号信息" → action="user_info", user_name="elonmusk"

  • "V神最近发了什么" → action="user_tweets", user_name="VitalikButerin"

  • "这条推文的回复" → action="tweet_replies", tweet_id="..."

  • "全球趋势" → action="trends"

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "twitter"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoLocal records per business list (default 20 and max 20). Does not change upstream page size. Omitted records from a shortened page are not recoverable through the next upstream cursor.
queryNoSearch query string. Required for: search\, search_users. Supports Twitter advanced search operators. Up to 500 runes; longer queries silently truncated.
woeidNoYahoo WOEID for trends location (1=Worldwide\, 23424977=US). Default 1.
actionYesWhich Twitter operation to perform: search | user_info | user_about | batch_user_info | search_users | user_tweets | user_timeline | user_mentions | followers | followings | verified_followers | check_follow | tweets_by_ids | tweet_replies | tweet_replies_v2 | tweet_thread | tweet_quotes | tweet_retweeters | trends | community_tweets | article | space_detail | list_tweets | list_timeline
cursorNoPagination cursor from previous response's next_cursor field.
list_idNoTwitter List ID. Required for: list_tweets\, list_timeline.
user_idNoNumeric Twitter user ID. Required for: user_timeline\, verified_followers. Also accepted by user_tweets as alternative to user_name.
space_idNoTwitter Space ID. Required for: space_detail.
tweet_idNoSingle tweet ID. Required for: tweet_replies\, tweet_replies_v2\, tweet_thread\, tweet_quotes\, tweet_retweeters\, article.
user_idsNoComma-separated numeric user IDs. Required for: batch_user_info. Maximum 20 entries including duplicates; larger batches are rejected before querying upstream.
tweet_idsNoComma-separated tweet IDs. Required for: tweets_by_ids. Maximum 20 entries including duplicates; larger batches are rejected before querying upstream.
user_nameNoTwitter handle (without @). Required for: user_info\, user_about\, user_tweets\, user_mentions\, followers\, followings\, check_follow.
verbosityNoPer logical prose field: concise 200 Unicode characters | standard 600 (default) | detail 2000. Includes nested text; detail remains capped. Independent of record limit.
query_typeNoSearch result ordering: Latest (default) | Top. Only for: search.
time_rangeNoExplicit caller-requested recency window\, written as <number><unit> where unit is h|d|w|m|y — e.g. 1h\, 4h\, 1d\, 1w\, 1m\, 6m\, 1y. Supply this field when a time constraint is required; the server does not infer a window from query text. Only for: search.
community_idNoTwitter Community ID. Required for: community_tweets.
include_repliesNoInclude reply tweets in results. For: user_tweets.
target_user_nameNoSecond user handle for relationship check. Required for: check_follow.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • changedInput schema / properties / tweet_ids / description
      Previous value: -"Comma-separated tweet IDs. Required for: tweets_by_ids."New value: +"Comma-separated tweet IDs. Required for: tweets_by_ids. Maximum 20 entries including duplicates; larger batches are rejected before querying upstream."
    • changedInput schema / properties / user_ids / description
      Previous value: -"Comma-separated numeric user IDs. Required for: batch_user_info."New value: +"Comma-separated numeric user IDs. Required for: batch_user_info. Maximum 20 entries including duplicates; larger batches are rejected before querying upstream."
  2. First observed

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered and the description doesn't contradict it. The description adds genuine context beyond that: the return shape (raw twitterapi.io payload per action) and cursor-based pagination via next_cursor. It stops short of noting rate limits, auth requirements, or how `limit` truncation interacts with cursors — but that last point is already carried by the schema.

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 structure is strongly front-loaded (PURPOSE → COVERS → BOUNDARIES → USAGE → RETURNS → EXAMPLES), which matters for a 24-action multiplexer. It is long, and the per-action param list partially duplicates the schema's "Required for" annotations, but for a tool of this breadth the length is largely justified.

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?

There is no output schema, so the description must explain returns — and it does, stating the payload type per action and the next_cursor pagination contract. Combined with the complete action inventory, boundary routing, and four worked examples covering the most common intents, an agent has everything needed to call this correctly.

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% and every parameter carries a "Required for: ..." note, so baseline would be 3. The description adds value by regrouping those constraints by action, letting the agent pick an action and immediately see its minimal param set, plus defaults like woeid=1 for trends and comma-separated batch formats. It does not explain the limit/verbosity interaction, so it is not a full 5.

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 opening sentence names a specific resource and scope ("raw operations on a specific account, tweet, search, list, or community"), and the COVERS block enumerates the concrete action families. The BOUNDARIES section explicitly contrasts it with signal(kol_call) and news(sources=["twitter"]), so an agent can distinguish it from all three siblings without opening a schema.

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?

BOUNDARIES gives both when-to-use and when-NOT-to-use with named alternatives and the condition that selects each ("for 'what are KOLs calling' use signal(kol_call)"). The USAGE block further maps each action to its required parameters, so selection and invocation guidance are both explicit.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources