@xcrap/mcp

Resolve up to 50 post URLs or ids in a single call.

This is the right tool whenever you have more than two or three links. One bulk call costs one request against a 10-per-5-minutes budget, while the same posts fetched individually cost one request each against a 60-per-minute budget — and bulk runs them concurrently, so it is several times faster.

Failures are per item, not per request: one dead link in a batch of fifty returns forty-nine posts and one error entry, so a single bad URL never loses the batch.

When to use this instead of the alternatives:

• Use this for a list of links, a set of ids extracted from a document, or a batch job.

• Use xcrap_get_tweet for a single post — bulk uses a cheaper, lighter source and returns slightly less detail per post (no media variants or entity offsets).

• Use xcrap_get_thread for connected posts by one author; bulk does not know they are a thread.

Args:

• urls (string[], required): 1-50 post URLs or numeric ids. Duplicates are removed by the server.

Returns markdown: a summary line of requested/succeeded/failed, then each post rendered in order, with an explicit error line for any that could not be resolved.

Errors: passing more than 50 URLs is rejected before any request is made — split the list into batches of 50.

Fetch one page of the accounts following an X/Twitter account, each with its name, handle, bio, follower count and verification.

Use this for "who follows @x", "who does @x follow", or to find the other accounts in someone's circle. X decides the page size (usually a few dozen accounts); pass next_cursor to continue, and stop when it is null.

When to use this instead of the alternatives:

• Use xcrap_get_user for one account's own profile and follower count, rather than the list of accounts.

Args:

• handle (string, required): "jack", "@jack" or a profile URL.

• cursor (string): the next_cursor from a previous call. Omit for the first page. Do not invent one.

• format ('markdown' | 'json'): default 'markdown'.

Returns markdown: a heading, then one line per account — name, handle, follower count — with its bio underneath, and a "Next page" cursor line when there is more. Returns json: { handle, relation, count, next_cursor, users[ ] }.

Costs 20 calls/minute. Protected accounts return 404; accounts that opted out of XCrap are left out of the list.

Fetch one page of the accounts followed by an X/Twitter account, each with its name, handle, bio, follower count and verification.

Use this for "who follows @x", "who does @x follow", or to find the other accounts in someone's circle. X decides the page size (usually a few dozen accounts); pass next_cursor to continue, and stop when it is null.

When to use this instead of the alternatives:

• Use xcrap_get_user for one account's own profile and follower count, rather than the list of accounts.

Args:

• handle (string, required): "jack", "@jack" or a profile URL.

• cursor (string): the next_cursor from a previous call. Omit for the first page. Do not invent one.

• format ('markdown' | 'json'): default 'markdown'.

Returns markdown: a heading, then one line per account — name, handle, follower count — with its bio underneath, and a "Next page" cursor line when there is more. Returns json: { handle, relation, count, next_cursor, users[ ] }.

Costs 20 calls/minute. Protected accounts return 404; accounts that opted out of XCrap are left out of the list.

Fetch the replies under an X/Twitter post, most liked first or newest first, with the post itself on top.

This is how you answer "what are people saying about this post", "what did the replies think" or "find the strongest pushback on this". Only direct replies come back — a reply to a reply belongs to its own conversation.

When to use this instead of the alternatives:

• Use xcrap_get_tweet if you only need the post.

• Use xcrap_get_thread for the author's own follow-up posts; replies by other people are not a thread.

Args:

• url (string, required): the post's URL or bare numeric id.

• sort ('top' | 'recent'): 'top' (default) for the most liked first, 'recent' for the newest first.

• format ('markdown' | 'json'): default 'markdown'.

Returns markdown: a "Replies to" heading, the post, then each reply with its author, timestamp, text and metrics. Returns json: { tweet_id, tweet_url, sort, count, tweet{...}, replies[ ] }.

There is no paging: this is the single page X serves for the post, up to about a hundred replies. Costs 20 calls/minute. A 404 means the post is deleted, private or never existed.

Unroll a whole X/Twitter thread from any post in it, returning every post by the original author in order as one readable document.

This is the tool for "read this thread and summarise it". Give it the link the user pasted — first post, last post or anywhere in the middle — and it reconstructs the run. Replies by other people are excluded: a thread is one author's chain, not the surrounding conversation.

When to use this instead of the alternatives:

• Use this when the link is part of a series of connected posts, or when a single post ends mid-thought.

• Use xcrap_get_tweet if you only want the one post the URL points at (a thread costs more: 20 calls/minute).

• Use xcrap_get_user_tweets to read an account's recent posts generally, rather than one connected chain.

Args:

• url (string, required): any post in the thread, as a URL or numeric id.

• max_tweets (number, 1-100): how many posts to unroll, default 25. Lower it if a response comes back truncated.

• format ('markdown' | 'json'): default 'markdown'.

Returns (markdown): the author heading, then every post in order with its timestamp, text and metrics. Returns (json): { root_id, author{...}, count, truncated, tweets[ ] }. The 'truncated' flag is true when the thread is longer than max_tweets.

Note: threads are reconstructed from X's public data, so a very old thread may come back partial — 'truncated' and the post count tell you when that happened.

Fetch what is trending on X/Twitter right now: the topic or hashtag, its context line where X provides one, and its post volume.

Use this for "what is trending", "what is everyone talking about on X" or as a starting point before searching for posts on a topic. The list is live and refreshed every few minutes, so the same call twice an hour apart will legitimately return different results.

Args:

• count (number, 1-50): how many trends, default 20.

Returns markdown: a table of rank, topic, context and post count.

Note: trends are global, not localised to a country or city. If the list comes back empty, X was not serving trends at that moment — retry in a minute rather than concluding nothing is trending.

Fetch one post (tweet) from X/Twitter by URL or numeric id, including its full text, author, timestamp, engagement metrics, attached media, poll, quoted post and community note.

Works without any X account, API key or login, and reads posts that x.com refuses to show logged-out visitors. Long-form posts are returned in full, not truncated at 280 characters.

When to use this instead of the alternatives:

• Use this for ONE specific post. It is the cheapest tool here (60 calls/minute).

• Use xcrap_get_thread if the post is the start or middle of a multi-post thread and you want the whole thread unrolled.

• Use xcrap_bulk for several posts at once — it is one call instead of N and has a far larger effective budget.

• Use xcrap_list_media if you only need the image or video files attached to the post.

Args:

• url (string, required): post URL or bare numeric id, e.g. "https://x.com/jack/status/20", "https://twitter.com/jack/status/20" or "20".

• format ('markdown' | 'json'): default 'markdown'.

Returns (markdown): a heading with the author's name and handle, the timestamp and permalink, the post text, and a line of metrics (likes, reposts, replies, quotes, bookmarks, views). Returns (json): { id, url, text, lang, created_at, created_timestamp, author{...}, metrics{likes,retweets,replies,quotes,bookmarks,views}, media[], poll, quote, replying_to, replying_to_status, community_note, possibly_sensitive, is_note_tweet, entities[], client }.

Errors: 404 means the post is deleted, private or never existed and retrying will not help; 451 means the author opted out of XCrap.

Fetch a public X/Twitter profile by handle: display name, bio, location, website, join date, verification status, avatar and banner URLs, and follower/following/post counts.

Use this to answer "who is @x", to check whether an account exists, or to get follower counts. It returns the profile only — not the account's posts.

When to use this instead of the alternatives:

• Use xcrap_get_user_tweets to read what the account has actually posted.

• Use xcrap_get_tweet if you have a link to a specific post rather than an account.

Args:

• handle (string, required): "jack", "@jack" or "https://x.com/jack". Handles are 1-15 letters, digits or underscores; a display name will not work.

• format ('markdown' | 'json'): default 'markdown'.

Returns (markdown): name and handle heading, bio, and a table of followers, following, posts, media count, join date, verification and website. Returns (json): { id, screen_name, name, url, description, location, website, avatar_url, banner_url, joined, verified, verified_type, protected, metrics{posts,followers,following,likes,media} }.

Errors: 404 means no such account, or it is suspended or private.

Fetch many of an account's posts in one call — walking its timeline page by page — optionally limited to a date window.

This is for "everything @x posted in March", "their last 200 posts" or "summarise what they said about Y this year". It replaces paging xcrap_get_user_tweets yourself, and it counts as one call against its budget however many pages it walks.

When to use this instead of the alternatives:

• Use xcrap_get_user_tweets for a quick look at the latest posts.

• Use xcrap_get_thread for one connected chain of posts.

Args:

• handle (string, required): "jack", "@jack" or a profile URL.

• max_posts (number, 1-200): stop after this many posts, default 50. The API allows up to 1,000, but a result that large will not fit in a context window; narrow the dates instead.

• since (string): oldest post to include, as a date such as "2025-01-01".

• until (string): newest post to include, as a date.

• include_replies (boolean): default false. Set true to include the account's replies to other people.

Returns markdown: a "Post history" heading with the count and the window, then every post with its timestamp, permalink, text and metrics.

Costs 5 calls per 5 minutes — it is the most expensive tool here, so choose the window before calling rather than calling repeatedly. It takes about a second per twenty posts, and the further back a window sits, the patchier X's timeline is — an old window can legitimately come back empty.

Fetch a page of an account's posts, newest first, with text, timestamps and metrics for each.

This is how you answer "what has @x been posting about", "find their recent posts about Y" or "what did they say this week". Paging is cursor-based because a timeline moves while you read it: pass the next_cursor from the previous call to get the next page.

When to use this instead of the alternatives:

• Use xcrap_get_user for the profile and follower counts instead of the posts.

• Use xcrap_get_thread when the posts you want are one connected chain rather than a general feed.

Args:

• handle (string, required): "jack", "@jack" or a profile URL.

• count (number, 1-100): posts per page, default 20. Above ~40 the result is likely to be truncated.

• cursor (string): the next_cursor from a previous call, to fetch the following page. Omit for the first page. Do not invent one.

• exclude_replies (boolean): default true — the account's own posts only. Set false to include its replies to other people.

• media_only (boolean): default false. Set true for only posts carrying images or video.

Returns markdown: a "Posts by @handle" heading, the post count, then each post with its timestamp, permalink, text and metrics. To page further, call xcrap_get_user_tweets again with the cursor returned by XCrap.

Costs 20 calls/minute — one call returning 50 posts is far cheaper than 50 calls to xcrap_get_tweet.

List every downloadable file attached to a post — photos, videos and GIFs — with type, dimensions, duration, alt text, every available quality variant, and a direct download URL for each.

Use this when the user wants the image or the video from a post rather than its text: "download the video from this tweet", "what images are in this post", "get me the alt text". The download URLs it returns stream the original file straight from X and can be handed to the user or fetched directly.

When to use this instead of the alternatives:

• Use xcrap_get_tweet if you want the post's text and only need to know whether media exists.

• Use this when you need the actual file URLs, resolutions or alt text.

Args:

• url (string, required): post URL or numeric id.

Returns JSON (media metadata is field-level data, so this tool does not offer a markdown mode): { tweet_id, tweet_url, author, count, media: [ { id, type: "photo"|"video"|"gif", url, thumbnail_url, width, height, duration, format, alt_text, variants[ {url, container, bitrate} ], index, download_url } ] }

A post with no attachments returns count: 0 and an empty media array — that is a successful answer, not an error.

Full-text search over X/Twitter posts, with the same operators X's own search understands.

This is how you answer "what are people saying about Y", "find posts from @x about Z", "any recent posts linking to this site" or "what did @x post about the launch last week". The query is passed to X as-is, so operators work: from:nasa, to:jack, "exact phrase", -exclude, lang:en, filter:links, min_faves:100.

When to use this instead of the alternatives:

• Use xcrap_get_user_tweets or xcrap_get_user_history to read one account's posts without a topic.

• Use xcrap_get_trends for what is trending in general, with no query.

• Use xcrap_get_replies for the conversation under one specific post.

Args:

• q (string, required): the search query, operators included.

• feed ('latest' | 'top' | 'photos' | 'videos'): 'latest' (default) for newest first, 'top' for X's most relevant, or only posts with photos or videos.

• since (string): oldest post to match, as a date such as "2025-01-01".

• until (string): newest post to match, as a date.

• cursor (string): the next_cursor from a previous call, for the next page. Omit for the first page. Do not invent one.

• format ('markdown' | 'json'): default 'markdown'.

Returns markdown: a "Search:" heading with the result count and feed, then each post with its author, timestamp, permalink, text and metrics, and a "Next page" cursor line when there is more. Returns json: { query, feed, since, until, count, next_cursor, tweets[ ] }.

Costs 15 calls per 15 minutes — the tightest budget here. Write one precise query with operators instead of several broad ones. A 503 means search capacity is used up for now; wait for the time it gives.