# twitr.sh (remote · twitr.sh)

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

- Trust score: 60/100 (medium)
- Change this week: +4
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `twitr.sh`: 60/100 (this document), [markdown](https://verifymcp.io/servers/sh-twitr-twitr/api-mcp.md), [page](https://verifymcp.io/servers/sh-twitr-twitr/api-mcp)

## Channel facts

- Endpoint: `https://twitr.sh/api/mcp`
- Transports: `streamable-http`
- Auth: `none`
- Version: `1.0.0`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 63/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation not fully verified: no authorisation is required to call this server, and 14 tool(s) never declared a destructiveHint. The MCP spec treats an absent hint as destructive by default, so we cannot call this surface safe.
  - HTTPS is enforced; there's no plaintext access path.
  - The HSTS (Strict-Transport-Security) header is present.
  - DNSSEC check failed: this domain isn't protected by DNSSEC.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 47/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 4294 tokens (~306/item across 14 items; 14 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 85/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 56% of tool parameters carry a description.
- **Capabilities**: 60/100
  - Spec-recency check failed: implements MCP spec 2025-06-18; the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http sh-twitr-twitr https://twitr.sh/api/mcp
```

### Codex

```toml
[mcp_servers.sh-twitr-twitr]
url = "https://twitr.sh/api/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sh-twitr-twitr": {
      "type": "remote",
      "url": "https://twitr.sh/api/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add sh-twitr-twitr --url https://twitr.sh/api/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  sh-twitr-twitr:
    url: "https://twitr.sh/api/mcp"
```

### Other

```json
{
  "mcpServers": {
    "sh-twitr-twitr": {
      "type": "http",
      "url": "https://twitr.sh/api/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 60, 0)

- [security] The server rewrote its instructions, which are the text every model session reads
- [security] Tool “x_write” rewrote its description, which is the text the model reads
- [security] Tool “x_inbox” rewrote its description, which is the text the model reads

### 2026-08-02 (score 60, +1)

No change was recorded against any check on this day. Stability & Change Management went from 17 to 20. That category is still filling its 30-day observation window: 5 days of observed history at the previous scan, 6 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-31 (score 59, +1)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server
- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-29 (score 58, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-28 (score 57, +1)

- [functional regression] Schema quality: 270 → 304
- [functional improvement] Stability: unverified → 0.03

### 2026-07-27 (score 56)

First indexed and scored.

## MCP tools (14)

### `x_read` (~312 tokens)

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.

Input parameters:

- `count` (integer): trends: number of trends to return.
- `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.
- `resource` (string, required): Which read operation to run.
- `resultsLimit` (integer): Mandatory for followers-you-know: max results, billed per result.
- `source` (string): check-follower: source username.
- `target` (string): check-follower: target username.
- `woeid` (integer): trends: region WOEID (default 1 = worldwide).

### `x_search` (~360 tokens)

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

Input parameters:

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

### `x_timeline` (~274 tokens)

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.

Input parameters:

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

### `x_lists` (~150 tokens)

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.

Input parameters:

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

### `x_communities` (~150 tokens)

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.

Input parameters:

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

### `x_extract` (~357 tokens)

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.

Input parameters:

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

### `x_monitor` (~594 tokens)

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

Input parameters:

- `action` (string, required): Create a new monitor or extend an existing one.
- `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.
- `hours` (integer): Prepaid hours to purchase (default 1).
- `monitorId` (string): Monitor to extend (extend only).
- `query` (string): X search query to monitor (create, type=keyword).
- `type` (string): Monitor kind (create). Inferred from username/query when omitted.
- `username` (string): X handle to monitor, without @ (create, type=account).

### `x_draws` (~339 tokens)

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.

Input parameters:

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

### `x_write` (~535 tokens)

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.

Input parameters:

- `account` (string, required): A connected X handle owned by this wallet (no @).
- `action` (string, required): Which write to perform.
- `community_id` (string): post: optional community to post into.
- `is_note_tweet` (boolean): post: long-form note tweet.
- `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.
- `reply_to_tweet_id` (string): reply: the tweet being replied to.
- `target_tweet_id` (string): like|unlike|retweet|unretweet|delete_tweet: the target tweet ID.
- `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.
- `text` (string): post|reply|send_dm: the message body.

### `x_inbox` (~261 tokens)

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.

Input parameters:

- `account` (string, required): A connected X handle owned by this wallet (no @).
- `action` (string, required): Which inbox read to run.
- `folderId` (string): bookmarks: optional folder to read.
- `maxId` (string): dm_history: paginate before this message id.
- `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.
- `type` (string): notifications: optional filter (e.g. mentions).

### `x_profile` (~206 tokens)

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.

Input parameters:

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

### `x_community` (~186 tokens)

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.

Input parameters:

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

### `x_radar` (~148 tokens)

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.

Input parameters:

- `after` (string): Pagination cursor.
- `category` (string): Topic category filter.
- `hours` (integer)
- `limit` (integer)
- `region` (string)
- `source` (string): Trend source filter.

### `x_compose` (~198 tokens)

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.

Input parameters:

- `additionalContext` (string)
- `callToAction` (string)
- `draft` (string)
- `goal` (string)
- `hasLink` (boolean)
- `hasMedia` (boolean)
- `mediaType` (string)
- `step` (string, required): Composer step.
- `styleUsername` (string)
- `tone` (string)
- `topic` (string)

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/sh-twitr-twitr/api-mcp#diagnostics

## Score history

- 2026-08-03: 60
- 2026-08-02: 60
- 2026-08-01: 59
- 2026-07-31: 59
- 2026-07-29: 58
- 2026-07-28: 57
- 2026-07-27: 56

## Links

- Remote endpoint: https://twitr.sh/api/mcp
- Repository: https://github.com/lnvestor/twitr-skills
- Website: https://twitr.sh/
- Changelog RSS feed: https://verifymcp.io/servers/sh-twitr-twitr/api-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/sh-twitr-twitr/api-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/sh-twitr-twitr/api-mcp