# ViralHunt MCP Server

An [MCP](https://modelcontextprotocol.io) server for **[ViralHunt.io](https://viralhunt.io)** — the
all-in-one platform to **discover what's trending, curate it with your team, and publish everywhere**.
A BuzzSumo alternative with a built-in cross-network scheduler and an API that AI agents can drive
end to end.

Get a free token: **https://viralhunt.io/claude** → create the free account (free forever, no card, 24 content queries a day), then Account → API Access → Create access. Every token has a **permission group** (reader, writer, reviewer, publisher, full): a tool outside the group answers `403 insufficient_scope` naming what it lacks, and `viralhunt_account` shows the token its own group. Give an agent that writes a writer token and the one that reviews a reviewer token. Full API
docs: **https://viralhunt.io/api**.

## What an agent can do through this MCP server

These are the tools this server exposes (they drive the full **discover → time it → publish → verify →
correct** loop). Every number comes with its sample size and time window, so an agent can say how
much to trust it:

| Tool | What it does |
|------|--------------|
| `viralhunt_account` | **Who is this key** — plan, daily quota left, credits, per-endpoint rules (call first) |
| `viralhunt_trending` | **Find topics** — what's going viral on TikTok, Instagram, X, Facebook, Pinterest, Bluesky, Douyin, Reddit, Mastodon, Tumblr, Hacker News and news RSS, ranked by viral score, each post with `growth_24h` (how much it moved between our two most distant readings); `author` narrows to one page or account |
| `viralhunt_search` | **One keyword, every network** — merged and ranked, with per-network totals |
| `viralhunt_best_time` | **When to post** — best weekday + hour per network from the posts that went viral there (365-day sample, hit rate, sample size, your time zone, optional niche keyword) |
| `viralhunt_top_hashtags` | **Which hashtags** — top tags per network or across all, by engagement, posts or per-post; one tag's breakdown by network |
| `viralhunt_trending_sounds` | **Which sound** — trending audio on TikTok, Instagram Reels and Douyin, cross-network sounds first, with the posts that used it |
| `viralhunt_best_communities` | **Where to post** — best subreddits (peak per 1,000 members, timing, top posts, similar) and Bluesky custom feeds for a topic |
| `viralhunt_targets` | List your **brands/projects** and the connected accounts you can post to, with `needs_reconnect`, per-network `media_limits` and the projects linked in another language |
| `viralhunt_schedule` | **Publish now, schedule, or leave a draft** (text + media, per-network copy, a first comment, or a `design` on a template the app renders when a person approves). The answer carries `url`, `drafts_url`, `project_name`: a post for a person goes to Drafts complete and is handed over in one five-line message (id and project, `url`, angle, verification, the decision needed), the rest in `author_notes` |
| `viralhunt_drafts` | **The drafts waiting** for a review and an approval, with their reviews |
| `viralhunt_review_draft` | **Review a draft** — verdict, score, per-network warnings, a note (an agent as the team's checker) |
| `viralhunt_policy` | **The content rule** a reviewer applies before any OK: block and fix lists with codes, six scores and thresholds, per-network notes (read it first, every pass) |
| `viralhunt_review_queue` | **What needs a review**: posts in Review with no verdict on their current content |
| `viralhunt_calendar` | **The days worth a post**: international days and science/tech/space/health anniversaries with why, by window and category |
| `viralhunt_news_categories` | **The news categories** with counts; pass one as `category` to `viralhunt_trending` (rss) |
| `viralhunt_review_stats` | **Flags per collaborator** by week, fortnight or month: reviews, ok / fix / block, rule codes, average risk10 |
| `viralhunt_approve_draft` | **Send a draft** (owner/admin token, with the user's yes), optionally with its translations |
| `viralhunt_translate_post` | **The same post in another language** — the app adapts the copy and the template's texts for a linked project |
| `viralhunt_edit_log` | **Learn from the edits** — what people changed in drafts after the agent left them |
| `viralhunt_get_post` | Check a post's status + per-network results, permalinks and each network's own reason when it refused |
| `viralhunt_sync_post` | Refresh statuses from the networks |
| `viralhunt_update_post` | Edit a draft (anything, incl. the rendered `png`) or a still-scheduled post (body / media / networks / time) |
| `viralhunt_cancel_post` | Cancel the not-yet-published targets of a scheduled post, or drop a draft |
| `viralhunt_stats` | **What performed** — engagement of the published posts by network, by brand, top posts |
| `viralhunt_quotes` / `viralhunt_mark_quote_used` | The **quotes base** for daily-quote series (public domain by default, author context, portraits) |
| `viralhunt_recipes` / `viralhunt_recipe_ran` | **Standing orders** a person saved in the app: source, template, cadence; stamp a run |
| `viralhunt_list_templates` | Browse the **content template** library (on-brand layouts you fill; favourites first) |
| `viralhunt_get_template` | Get one template's full spec (html + css + variable manifest, what is `static` and what is `dynamic`, what it `suits`, the owner's `instructions`) to render |
| `viralhunt_upsert_template` | **Author or edit a template** — editing a curated one clones it into your copy (owner/admin) |
| `viralhunt_assign_template` | Assign a template to a project so its agents can use it (owner/admin) |
| `viralhunt_board_context` | The team's **Editorial Board** in one call: members (with ids), columns, categories |
| `viralhunt_create_card` | **Hand a post to a teammate** — create a kanban card (URL metadata auto-filled, assignee, priority, due date, category) |
| `viralhunt_move_card` | Move a card to another column (the `is_done` column completes it) |
| `viralhunt_my_cards` | The cards assigned to you (when the token belongs to an agent member of the team) |
| `viralhunt_card_comments` | Read or add comments on a card (notifies the assignee, mirrors to team chat) |

Guardrails baked in: it won't post to the wrong brand, only schedules in the future, drafts by default
unless the user asked to publish now, never uses another page's text or branded picture, checks each
network's media ceilings, and is told not to repost fake news / copyrighted media / spam.

## Changelog

- **1.1.31 (2026-10-26)** — `viralhunt_brand_webhook` takes `format` (json, discord, slack, auto) and `test: true` (one sample alert to the saved webhook, with what the receiver answered). The webhooks guide: https://viralhunt.io/webhooks.
- **1.1.30 (2026-10-26)** — `viralhunt_update_post` on a SCHEDULED post works per account: each account's own text and pictures are patched only when they changed, a changed `thread` (new parameter) on X/Threads makes that network's post again, added accounts are created and dropped ones deleted; the answer lists `patched`, `recreated`, `added`, `removed`, `refused`; nothing under 6 minutes before the post's time (`409 not_editable`).
- **1.1.29 (2026-10-24)** — `allow_duplicate` on `viralhunt_schedule` and `viralhunt_approve_draft`: the duplicate firewall refuses an account another post of the last 72 hours already carries the same text for (`duplicate_of`; `409 duplicate_post` when every account is one). A send whose every network was cut answers `status: processing` with `checking: true`: never create it again.
- **1.1.28 (2026-10-23)** — `all` and `limit` on `viralhunt_brand_hot` (the most commented threads too, rising first: the app's dashboard list); the answer carries `machine` (the always-on Chrome's heartbeat), so an empty list is read against whether anybody is searching.
- **1.1.27 (2026-10-22)** — `carousel` on `viralhunt_create_post` / `viralhunt_update_post`: several pictures are allowed only when the user asked for a carousel (else `422 multiple_pictures`); `png` replaces the post's picture instead of being added next to it; a post made on a template always has ONE picture, its render.
- **1.1.26 (2026-10-20)** — the brand's `voice` on every project of `viralhunt_targets` (the owner's playbook: read first, follow over the general rules, offer to draft one when empty); complete means every network's copy (X, Bluesky, Threads) in `overrides` in the same create, never a cut.
- **1.1.25 (2026-10-19)** — every picture on one of the organization's templates (create the template when none fits; pass the PNG and the `design`, a PNG alone is a flat file nobody can edit); the working agreement in `viralhunt_schedule`: a post for a person goes to Drafts complete, never to Review unless asked, handed over in one five-line message with the `url` the answer gives; `url`, `drafts_url`, `project_id`, `project_name` on create, drafts rows and get.
- **1.1.24 (2026-10-19)** — `viralhunt_list_posts` (the queue and the history per target), `viralhunt_delete_post` (take a published target down), `account_id` on `viralhunt_cancel_post`; `retry` on a timed-out create needs `force`.
- **1.1.23 (2026-10-18)** — cards: `assigned_to` by id, name or email on `viralhunt_create_card`; `viralhunt_assign_card`, `viralhunt_get_card`, `viralhunt_list_cards`, `viralhunt_archive_card`. Drafts rows carry `publishes[]` (the text each account really sends).
- **1.1.22 (2026-10-15)** — `viralhunt_brand_keywords` takes `run: true` ("search now"); `viralhunt_brand_status` carries `machine` (is the always-on machine alive).
- **1.1.21 (2026-10-15)** — Brand watch: `viralhunt_brand_status`, `viralhunt_brand_keywords`, `viralhunt_brand_hot` (the discussions heating up right now, with links), `viralhunt_brand_alerts`, `viralhunt_brand_webhook` (signed deliveries to the brand's own agent).
- **1.1.20 (2026-10-15)** — `viralhunt_translate_post` describes what comes back (`shortened`, `overrides`, no em dashes) and the one-brand-two-languages pattern.
- **1.1.19 (2026-10-14)** — `viralhunt_schedule` takes `stage` and `assigned_to`; `viralhunt_update_post` takes `assigned_to` and answers the stage after the edit; `viralhunt_drafts` filters by `assigned_to`; `viralhunt_get_post` carries the full drafts shape (overrides, design, render…); `viralhunt_get_template` with `preview` shows a template before any post; a too-long text answers `text_too_long` instead of a 500.
- **1.1.18 (2026-10-14)** — `design` is always sent for a template-made picture (and `viralhunt_update_draft` repairs a PNG-only post with it): the app can then edit the image.
- **1.1.17 (2026-10-14)** — `viralhunt_trending` takes `sort: most_commented` on every network that counts comments (tiktok new; facebook and pinterest map it to most_comments, x, bluesky and mastodon to most_replied).
- **1.1.16 (2026-10-13)** — `viralhunt_upsert_template` takes `action: archive`; update works whether the action comes in the body or the URL; `viralhunt_list_templates` takes `scope`, `per_page`, `page` and lists the organization's own templates first.
- **1.1.15 (2026-10-13)** — every draft is an Editorial Board card (`card_id` on create) that moves with the post; `design_fields` on update fixes the texts inside a designed image (a trusted reviewer too); template authors without admin ("Creates templates" on Team); templates never carry code (`removed` in the answer).
- **1.1.11 (2026-10-08)** — approve by a member token on its own graded post (when ticked on Team); review_stats carries avg_score, self_published, published_over_fix.
- **1.1.10 (2026-10-07)** — the reviewer's edit boundary (overrides and kind only, when trusted); text_limit per account.
- **1.1.9 (2026-10-07)** — `kind` on create and update (fact | meme | quote | opinion | promo): the reviewer applies only that kind's rules.
- **1.1.8 (2026-10-07)** — `overrides[account]` takes `first_comment` and `thread` per account; Bluesky/Mastodon threads as a reply chain.
- **1.1.7 (2026-10-07)** — `author_notes` on create and update: the source link for the reviewer, never published.
- **1.1.6 (2026-10-07)** — the safety catch on a trusted reviewer's OK (risk_threshold), project_lang on drafts, review_stats for trusted reviewers.
- **1.1.5 (2026-10-07)** — `viralhunt_calendar`: the calendar base (international days and anniversaries, with why), mark_used.
- **1.1.4 (2026-10-07)** — `viralhunt_news_categories` and `category` on `viralhunt_trending` (rss); unknown parameters are a 422 on the API.
- **1.1.3 (2026-10-07)** — the policy describes the kinds (fact, meme, quote, opinion, promo): a meme or a quote never gets a source or DOI demand.
- **1.1.2 (2026-10-06)** — `content_hash` on `viralhunt_review_draft` (409 content_changed when the post moved under the reviewer); self review is by user, not token.
- **1.1.1 (2026-10-06)** — the reviewer's four extra checks (picture against text, spelling, AI-written, facts with the DOI rule), `risk10` 1 to 10 on every review, `viralhunt_review_stats` (flags per collaborator).
- **1.1.0 (2026-10-05)** — the reviewer job: `viralhunt_policy`, `viralhunt_review_queue`, `needs_review` on drafts; the server recalculates the verdict and names in `sent.skipped` the rule that kept an OK from sending.
- **0.3.0 (2026-09-28)** — drafts and review (`viralhunt_drafts`, `viralhunt_review_draft`,
  `viralhunt_approve_draft`, `viralhunt_edit_log`), translation into a linked project's language
  (`viralhunt_translate_post`), `design` on a post and `png` on update, `viralhunt_search`,
  `viralhunt_account`, `viralhunt_stats`, `viralhunt_quotes`, `viralhunt_recipes`, `viralhunt_sync_post`;
  `author` and free-form `time_range` on trending; `media_limits`, `needs_reconnect` and language links on
  targets; templates say what is static, dynamic and what they suit; honest post statuses with each
  network's reason.
- **0.2.x (2026-09-08)** — best time to post, top hashtags, trending sounds, best communities, the editorial
  board; Reddit, Mastodon, Tumblr and Hacker News on trending; `growth_24h` documented.
- **0.1.x (2026-08)** — trending, targets, publish/schedule, get, update, cancel, content templates.

## What ViralHunt the platform does (beyond this MCP)

ViralHunt is a full product; the tools above are the agent-drivable slice. The rest lives in the app
(and some via the [REST API](https://viralhunt.io/api)):

- **Trending Radar** — a live cross-network feed of viral content by niche and time window.
- **Cross-network publishing & scheduling** — schedule/publish to **up to 11 networks** (Instagram,
  Facebook, TikTok, X, LinkedIn, YouTube, Pinterest, Threads, Bluesky, Telegram, Google Business),
  per brand.
- **Editorial Board (team)** — a kanban to curate before publishing: columns, categories, assignments,
  comments and team chat, so a team manages what goes out. (Cards/columns/comments are in the REST API.)
- **Auto-DM (comment → DM automation)** — when someone comments your keyword on Instagram, ViralHunt
  auto-replies and sends them a DM — like ManyChat, but flat pricing, unlimited contacts, and a monthly
  cap that resets. Configured in the app (runs via webhooks); Facebook next.
- **Reports** — what each brand/network actually did: posts, reach, DMs sent, replies, top content.

> Note: Auto-DM and Reports are **product features**, not tools this MCP exposes today. The editorial
> board is exposed (context, cards, moves, comments) so an agent can hand content to a team instead
> of publishing it directly.

## Install (Claude Desktop / Cline)

```json
{
  "mcpServers": {
    "viralhunt": {
      "command": "npx",
      "args": ["-y", "viralhunt-mcp"],
      "env": { "VIRALHUNT_API_KEY": "vhk_your_token_here" }
    }
  }
}
```

Config: `VIRALHUNT_API_KEY` (your `vhk_…` token, required) and `VIRALHUNT_BASE_URL` (optional, defaults
to the production API). Run locally: `VIRALHUNT_API_KEY=vhk_... npx viralhunt-mcp` (Node ≥ 18).

Listed on the [Official MCP Registry](https://registry.modelcontextprotocol.io) as
`io.github.rodvan/viralhunt-mcp`. License: MIT.