# XTapDown MCP Server

An MCP (Model Context Protocol) server that gives any LLM client — Claude
Desktop, Cursor, Cline, Continue, or your own agent — direct access to
the [XTapDown](https://xtapdown.com) X (Twitter) creator toolkit.

Fourteen tools, read-only, zero auth, free.

## Tools (14)

Full coverage of every XTapDown web tool — 4 downloaders (video, GIF, image, full archive) consolidated under a single `download_tweet` since they share one X syndication endpoint.

| Tool | Description |
|------|-------------|
| `download_tweet` | Download any X post — video, GIF, image, or article. Returns direct media URLs, author info, engagement stats. Covers /twitter-video-downloader, /twitter-gif-downloader, /twitter-image-downloader and /tweet-downloader. |
| `get_x_hashtags` | Curated X hashtags for a niche (tech, finance, marketing, politics, sports, business, ai, gaming, writing, fitness, design, general) + strategy tips. |
| `get_best_time_to_post_x` | Best posting windows on X by country (12 countries) with the reasoning behind each slot. |
| `generate_tweet_hook` | Battle-tested tweet hook formulas across 8 categories (Curiosity, Controversy, Authority, List, Story, Question, Numbers, Reframe). |
| `calculate_x_engagement_rate` | Compute engagement rate using the public follower-based formula, with tier-aware benchmark bands. |
| `calculate_x_ads_revenue` | Estimate monthly Premium creator ads-revenue-share payout from impressions, with eligibility check. |
| `get_x_trends` | Live trending topics on X by country (17 countries) — refreshed roughly hourly. |
| `count_tweet_characters` | X-weighted character count (CJK ×2, emoji ×2, URLs ×23 t.co) with thread-split warning. |
| `split_long_text_into_thread` | Split long text into ≤280-char numbered tweets respecting sentence/word boundaries + t.co URL math. |
| `build_x_search_url` | Build an X advanced-search URL from structured filters (from:, since:, min_faves:, lang:, filter:media, etc). |
| `generate_fancy_unicode_text` | Convert ASCII to fancy Unicode (bold, italic, monospace, script, double-struck, small-caps, bold-italic) for bios and tweets. |
| `get_tweet_screenshot_url` | Deep-link to the XTapDown screenshot tool with theme + background presets pre-filled (PNG rendering happens client-side in the browser). |
| `find_viral_tweets_for_niche` | Top creators in a niche plus 3 viral tweet templates with explanations of why each one works. |
| `get_x_search_operators_cheatsheet` | Full X advanced-search operator reference, grouped by category, updated for 2026. |

## Install

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "xtapdown": {
      "command": "npx",
      "args": ["-y", "xtapdown-mcp"]
    }
  }
}
```

### Cursor / Cline / Continue

Add a stdio MCP server entry pointing at:

```
npx -y xtapdown-mcp
```

### From source

```bash
git clone https://github.com/farukkolip/xtapdown-mcp
cd xtapdown-mcp
npm install
npm run build
node dist/index.js
```

### Hosted (HTTP)

Set `PORT=3000` (or any port) to start the server in HTTP / SSE mode for
Smithery-style hosted deployments. Endpoint: `POST /mcp` and `GET /mcp`
following the MCP Streamable HTTP transport spec.

## Example interactions

> *"Download this tweet for me: https://x.com/.../status/..."*
> → `download_tweet` returns direct MP4, thumbnail, author handle, like count.

> *"What's the best time to post on X if my audience is in Türkiye?"*
> → `get_best_time_to_post_x` returns day-by-day windows in TRT.

> *"My 50k-follower account got 1,200 likes, 80 reposts, 150 replies. What's my engagement rate?"*
> → `calculate_x_engagement_rate` returns 2.86% (Good — Mid tier).

> *"I've been getting 8M impressions a month. Would I qualify for ads revenue share?"*
> → `calculate_x_ads_revenue` returns: projected 24M / 25M threshold = not yet eligible, ~$60/mo estimated payout if you cross.

## Why MCP?

X's API is largely closed to creators. Most third-party tools require
paid subscriptions or scrape with hidden rate limits. This server uses
X's own public syndication endpoint (the same one embed widgets use)
plus inline curated content data, so it works offline-free, no auth, no
quota, no surprises.

Once added to your MCP client, the LLM can autonomously fetch tweet data
and apply XTapDown's research data to whatever you're working on —
content drafts, social audits, strategy threads, monetization math.

## Design boundaries

This server is **read-only by construction**. It has no write tools, no
account, no token, no OAuth. Every tool either reads public data through
X's syndication endpoint or does local computation. The two tools that
produce text (`generate_tweet_hook`, `split_long_text_into_thread`)
return it to the caller — posting is a separate, human action in a
different tool. The approval gate is structural: it is the absence of a
post tool, not a flag.

What the model gets back on failure (since 1.3.0):

- Every failed call sets `isError: true`, so the model can branch on
  failure instead of pattern-matching an emoji in text.
- Network calls time out after 15 s and report it as a timeout, distinct
  from a connection failure.
- HTTP 429 from upstream is returned as *"rate limited, wait N seconds"*
  (from `Retry-After` when present), not as a bare status code.
- A protected account (403) and a deleted post (404) are reported as
  different situations.

What it does not do: it does not add its own rate limit on top of the
upstream. A read tool pointed at someone can still be used to bulk-collect
public data. The only defence is that it reads what X already serves to
anyone.

## Data sources

- **Tweet data:** `cdn.syndication.twimg.com/tweet-result` (public, auth-free)
- **Hashtags / best times / hooks / benchmarks:** XTapDown editorial library, 2026 updated
- **Engagement math:** public follower-based formula `(likes + reposts + replies + bookmarks + quotes) / followers × 100`
- **Ads revenue math:** X Premium Creator Ads Revenue Sharing documented terms (25M imp/3mo + 500 verified followers + Premium)

## Related

- [tiktapdown-mcp](https://www.npmjs.com/package/tiktapdown-mcp) — TikTok equivalent
- [xtapdown.com](https://xtapdown.com) — full web toolkit with 17 tools

## License

MIT — © Faruk Kolip