twitr.sh

Measured conclusion: Deep-tested. L2 outcome: tools_ok.

X/Twitter reads, search, monitors and posting. Pay-per-call in USDC — no signup, no API keys.

Add to your agent

Copy this into your MCP client config:

{
  "mcpServers": {
    "twitr.sh": {
      "url": "https://twitr.sh/api/mcp",
      "transport": "streamable-http"
    }
  }
}

Measured tools (14)

• x_read

  Read live X/Twitter data: look up a single tweet or user profile, batch-read up to 100 tweets or users at once, check whether one account follows another, fetch trending topics by region, extract a long-form article, or download tweet media. Pay per call in USDC — no API key, no signup; failed calls are never charged. Guidance: resource=get-tweet|get-user (id), batch-tweets|batch-users (ids array, ≤100), check-follower (source+target usernames), trends (optional woeid/count), article (tweet id), followers-you-know (id + mandatory resultsLimit), download-media (id or ids ≤50 — returns media file URLs on THIS origin; links live 7 days). Fixed-price per call/id except followers-you-know which is per-result.

  Parameters:

  • resource (required) — string — Which read operation to run.
  • id — string — Tweet ID, user ID, or username (depends on resource).
  • ids — array — batch-tweets|batch-users: up to 100 tweet IDs or user IDs/usernames.
  • count — integer — trends: number of trends to return.
  • woeid — integer — trends: region WOEID (default 1 = worldwide).
  • source — string — check-follower: source username.
  • target — string — check-follower: target username.
  • resultsLimit — integer — Mandatory for followers-you-know: max results, billed per result.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_search

  Search X/Twitter tweets with the full operator set — keyword, exact phrase, from-user, language, date range, media type, minimum likes/retweets, verified-only — or search user profiles by keyword. Billed per tweet returned against your resultsLimit cap. Built for tracking what people say about a topic, brand, or ticker in real time. Guidance: type=search-tweets (default): q required, resultsLimit MANDATORY (billed per tweet returned). Supports the full filter set: fromUser, language, sinceDate/untilDate, mediaType, minFaves, verifiedOnly, exactPhrase, excludeWords, advancedQuery, and more. type=search-users: q required; returns one results page per call — follow report.next_cursor for the next page (each page is a separate paid call).

  Parameters:

  • q (required) — string — Search query (X operator syntax supported for tweets).
  • type — string — Search tweets (default) or users.
  • cursor — string — search-users: pagination cursor from a previous call's report.next_cursor.
  • fromUser — string
  • language — string
  • minFaves — integer
  • mediaType — string
  • sinceDate — string — YYYY-MM-DD
  • untilDate — string — YYYY-MM-DD
  • minReplies — integer
  • exactPhrase — string
  • minRetweets — integer
  • excludeWords — string
  • resultsLimit — integer — search-tweets: MANDATORY max tweets returned, billed per tweet.
  • verifiedOnly — boolean
  • advancedQuery — string — Raw X search operator string appended to q.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_timeline

  Fetch a user's X/Twitter timeline — their tweets, replies, likes, media posts, or mentions — plus follower and following lists, and per-tweet engagement lists (who replied, quoted, retweeted, or favorited). Billed per item returned. The building block for monitoring what an account posts or ranking accounts by activity. Guidance: kind selects the timeline: user-tweets|user-replies|user-likes|user-media|user-mentions|followers|following|verified-followers (id = user) or tweet-replies|tweet-quotes|tweet-thread|tweet-favoriters|tweet-retweeters (id = tweet). resultsLimit is MANDATORY — billed per item returned. Search-operator filters (fromUser, language, mediaType, minFaves, …) apply to tweet timelines.

  Parameters:

  • kind (required) — string — Which timeline to fetch.
  • id (required) — string — User ID/username or tweet ID (depends on kind).
  • resultsLimit (required) — integer — MANDATORY: max items returned, billed per item.
  • language — string
  • minFaves — integer
  • mediaType — string
  • verifiedOnly — boolean
  • includeReplies — boolean
  • includeParentTweet — boolean

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_lists

  Read an X/Twitter List: its combined tweet timeline, its member roster, or its followers. Billed per item returned. Useful for following a curated set of accounts as one feed. Guidance: kind=tweets|members|followers; id = list ID. resultsLimit is MANDATORY — billed per item returned. tweets supports sinceTime/untilTime and includeReplies.

  Parameters:

  • kind (required) — string — What to read from the list.
  • id (required) — string — List ID.
  • resultsLimit (required) — integer — MANDATORY: max items returned, billed per item.
  • sinceTime — string
  • untilTime — string
  • includeReplies — boolean

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_communities

  Read an X/Twitter Community: profile info, member and moderator rosters, the community's tweets, or keyword search inside the community. Fixed price for info; billed per item for rosters, tweets, and search. Guidance: kind=info (fixed price) or members|moderators|tweets|search (per-item — resultsLimit MANDATORY). id = community ID. search additionally requires q.

  Parameters:

  • kind (required) — string — What to read.
  • id (required) — string — Community ID.
  • q — string — search: query within the community.
  • resultsLimit — integer — Mandatory for members/moderators/tweets/search: max items, billed per item.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_extract

  Bulk-export X/Twitter data as downloadable datasets: followers, following, repliers, quoters, reposters, likers, mentions, full threads, list and community members, spaces, or people/tweet search results — 23 extractors. Runs async: you get a claim check immediately and poll a free status URL for the download link. Billed per result. Guidance: tool selects the extractor (23 options). Provide the matching target: targetTweetId (reply/repost/quote/thread/article/favoriters extractors), targetUsername (follower/following/verified/post/mention/likes/media), targetCommunityId, targetListId, targetSpaceId, or searchQuery (people_search, tweet_search_extractor). resultsLimit is MANDATORY — billed per result (article_extractor bills 5× per result). Runs ASYNC: the response is a claim check {snapshot_id, status_url}; poll status_url (free, SIWX) until status=ready for the download link. Idempotency-Key header is required so retries reuse the same job.

  Parameters:

  • tool (required) — string — Which extractor to run.
  • resultsLimit (required) — integer — MANDATORY: max results extracted, billed per result.
  • language — string
  • minFaves — integer
  • mediaType — string
  • sinceDate — string
  • untilDate — string
  • searchQuery — string
  • targetListId — string
  • verifiedOnly — boolean
  • targetSpaceId — string
  • targetTweetId — string
  • targetUsername — string
  • targetCommunityId — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_monitor

  Watch an X/Twitter account or keyword query in real time: new tweets, replies, quotes, mentions, hashtags, and profile changes, delivered to your agent by free polling or HMAC-signed webhooks. Prepaid by the hour with a hard stop at expiry — no open-ended billing. The way to track a brand, competitor, or topic without re-polling paid reads. Guidance: action=create needs username (account monitor, e.g. "vercel") OR query (keyword monitor, X search syntax, ≤512 chars), optional eventTypes — 21 available: post events (tweet.new, .reply, .retweet, .quote, .media, .link, .poll, .mention, .hashtag, .longform) for any monitor, plus profile-change events (profile.avatar/banner/name/username/bio/location/url/verified/protected/pinned_tweet/unavailable.changed) for ACCOUNT monitors only; default all applicable — and hours (1–168, default 1). action=extend needs monitorId + hours; hours append to the current expiry (total prepaid window ≤ 720h). Extend at least 5 minutes BEFORE expiry — extends inside the final 5 minutes are refused (unpaid) to keep settlement from racing the expiry teardown. PREPAID: the monitor stops and is removed at expires_at unless extended — no open-ended billing; early deletion does not refund remaining hours. Idempotency-Key header REQUIRED — retries replay the original monitor instead of re-charging (on the MCP door, retries are protected by single-use payment credentials instead). Pay with USDC on Base (x402) or Tempo (MPP); Solana is not offered for monitors (stateful resources need a recoverable owner wallet). After creation: poll events at /api/monitors/{id}/events (free — SIWX sign-in with the paying wallet; do NOT poll in a tight loop) or register an HTTPS webhook once at /api/webhooks to push signed events straight to your AI agent (Claude, OpenClaw, Hermes, or any endpoint) in real time. Manage monitors at /api/monitors (SIWX).

  Parameters:

  • action (required) — string — Create a new monitor or extend an existing one.
  • type — string — Monitor kind (create). Inferred from username/query when omitted.
  • hours — integer — Prepaid hours to purchase (default 1).
  • query — string — X search query to monitor (create, type=keyword).
  • username — string — X handle to monitor, without @ (create, type=account).
  • monitorId — string — Monitor to extend (extend only).
  • eventTypes — array — Event types to receive (default: all applicable). Post events (tweet.*) work for any monitor; profile-change events (profile.*.changed) apply to ACCOUNT monitors only.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_draws

  Run a provably fair giveaway on X/Twitter: pick crypto-random winners from a tweet's replies, with retweet, follow, hashtag, keyword, minimum-follower, and account-age conditions. Fixed price set upfront from your estimated entry count. Guidance: tweetUrl required. Optional: winnerCount (default 1), backupCount, uniqueAuthorsOnly, mustRetweet, mustFollowUsername, filterMinFollowers, filterAccountAgeDays, filterLanguage, requiredHashtags/Keywords/Mentions. Pricing is fixed upfront from the estimatedEntries you set (default 1000, max 10000) — set it near the tweet's reply count; that number is enforced as a hard cap. Payment settles before the draw runs, so pay only when you intend to run it; a failed draw does not auto-refund (contact support). Idempotency-Key header required — retries with the same key replay the original result instead of re-charging.

  Parameters:

  • tweetUrl (required) — string — Full tweet URL (https://x.com/user/status/ID).
  • backupCount — integer
  • mustRetweet — boolean
  • winnerCount — integer
  • filterLanguage — string
  • estimatedEntries — integer — Expected replies inspected — drives the fixed price (default 1000).
  • requiredHashtags — array
  • requiredKeywords — array
  • requiredMentions — array
  • uniqueAuthorsOnly — boolean
  • filterMinFollowers — integer
  • mustFollowUsername — string
  • filterAccountAgeDays — integer

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_write

  Act on X/Twitter through an account you connect: post a tweet, reply, like, retweet, follow or unfollow, send a DM, delete a tweet, remove a follower, or upload media. Ownership is checked server-side — an agent can only write as a handle its own wallet connected. Guidance: PREREQUISITE: connect an X account first — POST /api/x-accounts/start (free, SIWX) with {username} only; it returns a one-time connect_url the USER opens in their own browser to sign in there. Never ask the user for their X password, email, or 2FA secret. Poll GET /api/x-accounts until the handle shows linked, then reference it in `account`. Actions: post (text) | reply (text + reply_to_tweet_id) | like|unlike|retweet|unretweet|delete_tweet (target_tweet_id) | follow|unfollow (target_user_id — the NUMERIC user id, get it from x_read get-user) | remove_follower (target_user_id of the follower) | send_dm (target_user_id + text) | upload_media (media_url → returns media_id). You can only write as a handle THIS wallet connected (checked server-side; the input account is not trusted). Payment settles before the action runs and is non-refundable; a write may return status=pending_confirmation with an actionId to poll — do NOT resend. Idempotency-Key header is required so a retry replays the original result instead of acting twice.

  Parameters:

  • action (required) — string — Which write to perform.
  • account (required) — string — A connected X handle owned by this wallet (no @).
  • text — string — post|reply|send_dm: the message body.
  • media_ids — array — send_dm: optional uploaded media ids to attach.
  • media_url — string — upload_media: public URL of the file to upload; returns a media_id.
  • community_id — string — post: optional community to post into.
  • is_note_tweet — boolean — post: long-form note tweet.
  • target_user_id — string — follow|unfollow|send_dm|remove_follower: the numeric X user id of the target (not the @handle). Get it from x_read get-user.
  • target_tweet_id — string — like|unlike|retweet|unretweet|delete_tweet: the target tweet ID.
  • reply_to_tweet_id — string — reply: the tweet being replied to.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_inbox

  Read a connected X/Twitter account's private surfaces: bookmarks and bookmark folders, notifications, and DM history. Billed per item returned; readable only for handles this wallet connected. Guidance: PREREQUISITE: connect an X account (see /api/x-accounts/start). Reads act AS that account, so you can only read the inbox of a handle THIS wallet connected. action=bookmarks (optional folderId) | bookmark_folders | notifications (optional type) | dm_history (target_user_id required). bookmarks/notifications/dm_history are billed per item — set resultsLimit (1–10000). account (the connected handle) is required.

  Parameters:

  • action (required) — string — Which inbox read to run.
  • account (required) — string — A connected X handle owned by this wallet (no @).
  • type — string — notifications: optional filter (e.g. mentions).
  • maxId — string — dm_history: paginate before this message id.
  • folderId — string — bookmarks: optional folder to read.
  • resultsLimit — integer — Max items to return (billed per item); ignored for bookmark_folders.
  • target_user_id — string — dm_history: the other party's user id.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_profile

  Edit a connected X/Twitter account's profile: display name, bio, location, website link, avatar image, and banner image. Acts only on handles this wallet connected. Guidance: PREREQUISITE: connect an X account. Acts as a handle THIS wallet owns. action=update_profile (any of name, description, location, url) | set_avatar (media_url) | set_banner (media_url). account required. Payment settles before the change; Idempotency-Key required.

  Parameters:

  • action (required) — string — Which profile edit to make.
  • account (required) — string — A connected X handle owned by this wallet (no @).
  • url — string — update_profile: new website URL.
  • name — string — update_profile: new display name.
  • location — string — update_profile: new location.
  • media_url — string — set_avatar|set_banner: public image URL.
  • description — string — update_profile: new bio.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_community

  Manage X/Twitter Communities as a connected account: create a new community, join or leave an existing one, or delete a community you own. Guidance: PREREQUISITE: connect an X account. Acts as a handle THIS wallet owns. action=create (name, optional description) | join|leave (community_id) | delete (community_id + community_name confirmation). account required. Payment settles before the action; Idempotency-Key required.

  Parameters:

  • action (required) — string — Which community action.
  • account (required) — string — A connected X handle owned by this wallet (no @).
  • name — string — create: the community name.
  • description — string — create: optional community description.
  • community_id — string — join|leave|delete: the community ID.
  • community_name — string — delete: the community name, as confirmation.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_radar

  Trending topics and breaking stories across tech, dev, science, business, culture, politics, and entertainment — aggregated from multiple public sources with regional and time-window filters. Flat sub-cent price per call; the cheap first stop for what is happening right now. Guidance: Optional filters: category, region, hours (lookback), limit, source. Use report.next_cursor via `after` for the next page. Flat floor price per call.

  Parameters:

  • after — string — Pagination cursor.
  • hours — integer
  • limit — integer
  • region — string
  • source — string — Trend source filter.
  • category — string — Topic category filter.

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

• x_compose

  Draft tweets with AI: generate variants from a topic and goal, refine an existing draft, or score a draft for likely engagement — with tone, call-to-action, and style-matching options. Flat sub-cent price per step. Guidance: step=generate (topic + goal required; optional tone/styleUsername/additionalContext/callToAction/mediaType/hasLink/hasMedia), refine (draft required), or score (draft required). Returns text variants with scores and suggestions. Flat floor price per call.

  Parameters:

  • step (required) — string — Composer step.
  • goal — string
  • tone — string
  • draft — string
  • topic — string
  • hasLink — boolean
  • hasMedia — boolean
  • mediaType — string
  • callToAction — string
  • styleUsername — string
  • additionalContext — string

  Hints: read-only not declared · destructive not declared · idempotent not declared · open-world not declared

Publisher website Repository

Measured by MCPYP probing. Untested fields are omitted, never estimated. Listing is always free; MCPYP never proxies calls or stores user tokens.