io.github.rodvan/viralhunt-mcp

Who this key is: plan (free/creator/studio/agency), requests per hour, whether it can publish, today's daily content-query quota (free plan: 24 shared across trending, search, best-time, hashtags, sounds, communities), credits balance, and per-endpoint rules. Call it once at the start and again on a 429 or 402, and set expectations from it (free plan: trending is 72h delayed and numbers are withheld, never print 0).

Send a draft (owner or admin token only, and never without the user's explicit yes). A draft blocked by its last review cannot be approved until it is fixed and reviewed again. `translations` makes the translated draft in each linked project in the same call (see viralhunt_translate_post). Returns {status, results, warnings, translations[]}.

Take a card off the board (archive). Nothing is deleted: a person restores it from the board's Archived view.

Hand a card to a member (id, name as the Team page shows it, or email); null unassigns. The member is notified. The answer carries the card with assigned_to_user_id and assigned_to_name read back.

Assign (or unassign) a content template to a project, so that project's agents see it via viralhunt_list_templates with assigned=true. Owner/admin only.

Where to post a topic: the best subreddits (network=reddit) or Bluesky custom feeds (network=bluesky) from our own measurements. Reddit rows are ranked by peak_per_1k, the best score we hold per 1,000 members (upside relative to size); no average score is published because a swept community's sample is its greatest hits. Each row carries members, sample.posts and the window of post dates. Pass `subreddit` for one community: timing (best UTC hours/day the climbing posts were posted), pace, flairs, type mix, top posts and similar communities. Bluesky rows carry posts, authors, avg_likes; pass `feed` (slug) for its top posts, authors, tags.

Best time to post on a network, measured on the posts that went viral there in the last 365 days (their OWN publish time). Returns best_slots (weekday + hour, ranked by average engagement, each with its sample size and hit_rate_pct = share of that slot's posts that reached the network's top 10%), worst_slot, today's best hours, by_hour and by_weekday tables, proof_posts, and sample {posts, window, from, to}. Read `confidence` (high >= 500 posts, medium >= 200, low) before quoting an hour. Hours are rotated to `timezone`; weekday aggregates stay UTC. With `keyword`, slots are recomputed on posts whose caption contains it; if that sample is under 200 posts the response says fallback:true and returns the network-wide slots instead.

The team's Editorial Board in one call: organization, members (people and agents, with ids to assign cards to), columns (with is_default / is_done flags) and categories. Call this before creating or moving cards.

What a brand was alerted about (each thread once), newest first; or, with mark_read_ids, mark alerts as taken so unread=true shows only what is left. Poll with since = your last read every 10 to 30 minutes, or set a webhook with viralhunt_brand_webhook.

The discussions about a brand heating up RIGHT NOW: posts of the last window that mention one of its keywords and whose comments grew by delta in the last hours (or were born loud), each with title, url, author, comments_from/to, delta, hours, alerted_at. The answer to 'where should I comment today': hand the user the biggest deltas with their links and a proposed comment. Never post the comment yourself.

Read a brand's keywords (what the always-on extension searches on X, Quora, Pinterest, Instagram, TikTok, Facebook, and the server on Reddit), or REPLACE the list (owner/admin token): keywords = product names, ingredients, the problems its buyers search for, #hashtags; up to 40; every keyword is machine time on every network. The answer carries the sweep state per network.

Every brand (project) of the organization and whether it is being watched: keywords count, category, webhook set, alerts in the last 7 days, and per network when the extension (or the Reddit cron) last searched its keywords (last_run, never_run, found). keywords: 0 = not watched, offer to set them; never_run with an old last_run = the always-on machine is off, tell the owner.

Read, set or clear the webhook where a brand's alerts are POSTed the minute the cron writes them (owner/admin to change it): JSON body {event: brand.alerts, project, alerts[], radar_url}, header X-VH-Signature = sha256=<hex HMAC-SHA256 of the raw body with the secret returned here>. Answer 2xx within 8 s; no retry (alerts stay readable). url null clears it.

The calendar base: the international days (UN, UNESCO, WHO) and the anniversaries of science, technology, space, health, the environment and civilization in a window of days, each with `why` (what is celebrated or what happened, and why it matters: write the caption FROM it, never from memory), kind (observance repeats every year; event, birth, death carry year and years_ago), category, origin, importance (3 = most brands can post about it, 2 = worth it inside its category, 1 = niche), image_url (a free Wikipedia thumbnail when there is one), source_url. Use days=7 or 31 to plan ahead; post on the day. The vh-ephemeris template fits an event or a birth; the news frame fits an observance. mark_used=true with calendar_id records what you posted.

Cancel the not-yet-published targets of a scheduled post, or with account_id stop ONE network (a pending retry, a timed-out create, a not-yet-published PostProxy post). A published target answers 409: use viralhunt_delete_post.

Read the comments on a card, or add one (comment set). New comments notify the assignee and appear in the team chat's #board channel.

Create a card on the Editorial Board: a piece of content to curate, with an optional post URL (title/description/image are filled from the URL's metadata when omitted), assignee, priority, due date, category and column. Returns the card with its id. Use it to hand a trending post to a teammate instead of publishing it directly.

Owner, admin or a member marked 'Their OK publishes': take a PUBLISHED target down from its network through PostProxy (the cleanup of a duplicate). Confirm on the network afterwards. Without account_id every published target of the post goes.

List the posts not yet sent (this project, or every project with all=true): stage 'draft' = being worked on, 'review' = complete and dated, waiting for an owner or admin. Each carries stage, body, media, targets, scheduled_at, overrides, card_id, submitted_via (api = from an agent), design, lang, translated_from_id, assigned_to and assigned_to_name (the member it is assigned to), review {score, verdict, reviewed_at, entries[]}, needs_review (no verdict on its current content), valid_verdict, content_hash and updated_at.

What people changed in drafts after an agent left them: one row per field (body, media, targets, scheduled_at, first_comment, overrides, thread, design) with before, after, who and when, plus by_field counts. Drafts with submitted_via=api came from an agent: those edits are what the person did not like. Read it at the start of each batch and apply the pattern (shorter captions, another picture, another hour).

One card of the Editorial Board: title, column (name, is_done), status, assignee (id and name), priority, due date, notes, archived.

Get the current status and per-network results (incl. permalinks) of a post you created. Also events[] (the delivery log: created, accepted by PostProxy, published with its link, refused with the reason, retried, canceled, reviewed, approved) and support_text, the text to hand the user when they ask what happened to a post. Statuses: scheduled (queued), processing (handed to the networks, or a target being retried), published (every target live), partial (some refused: each failed results[account].error carries the network's own words and error_message sums it up), failed, draft, canceled. The app retries a transient failure up to three times (results show retries, will_retry, retry_after); a final reason (dead connection, refused text, oversized video) is not retried: tell the user what to fix. The post carries the same fields as a viralhunt_drafts row whatever its status: stage, targets, media, overrides (what each account really sends: read it before an OK), thread, design (and render {html, css, format} on a draft or a post in review), card_id, kind, author_notes, lang, assigned_to, review {score, verdict, entries[]}, content_hash, needs_review.

Get one template's full spec: html, css, the variable manifest (with hard rules per variable), formats, palette tokens, embedded fonts, render_tech, plus what is `static` (the owner fixed it: logo, frame, signature, fixed texts; never move, cover or restyle it), what is `dynamic` (the variables you fill: the picture, the headline, the caption that is the post body), what it `suits` (news, photo, quote, number, tip, on_this_day, meme, any) and the owner's `instructions` (they override any general rule). Fill every dynamic {{variable}}, then render with headless Chrome at the chosen format's size and WAIT for [data-vh-ready='1'] before screenshotting .vh-card. With preview=true the answer is instead preview {document, html, css, format, variables}: a complete page with the example values (or `variables`) filled and the organization's design baked in, to open in a browser or render, so a template is seen before any post is made.

The organization's cards, newest first (up to 200): filter by column, status, assignee (id, name or email), unassigned or archived.

What went out and what did not: posts of the project (or the organization with all) by status, newest first, each target with status, PostProxy id, permalink, error, will_retry, timed_out (may be live), reconciled.

List ViralHunt content templates (layouts you fill and render yourself). Lean by design — no html/css — so use viralhunt_get_template for the one you'll actually render.

After scheduling a quote, mark it used for this organization so the next pick (unused=true) is a different one.

Move a card to another column (moving into the column flagged is_done completes it; a 'done' comment does not).

Cards assigned to the authenticated token's member (your own workload when you are an agent member of the team). Optional status filter.

The categories of the news corpus (source rss), with how many feeds carry each and how many articles arrived in the last 7 and 30 days. Read it once before asking for news on a subject, then pass a name as category on viralhunt_trending (source rss). Not the Editorial Board categories. Technology and Artificial Intelligence are separate categories.

The content rule a reviewer applies before any OK, kept on the platform so it changes without a release: what blocks a post (policy_* codes), what sends it back to Drafts (fix_* codes), the six scores (tos_risk, rights, fake_news, sensationalism, brand, grammar; 100 = clean) with the thresholds the server recalculates the verdict with, the extra readings every review carries (risk10 1 safe to 10 breaks a network's terms, image_match, ai_written), the kinds (fact, meme, quote, opinion, promo: a meme or a quote never gets a source or DOI demand), what changes per network, and the server rules an OK cannot bypass. Read it at the start of every review pass; never judge from memory.

Quotes ranked by our popularity score, for daily-quote series: text, author, author_context (description, born, died), work, categories, rights, popularity high|medium|low and author_image (portrait url, licence, credit). Default rights=public_domain (authors dead more than 70 years): keep it unless the user asks for a modern author, and with rights=any tell the user a quote is restricted before scheduling it under their brand. Write the caption's context FROM author_context and work, never from memory. categories_list=true lists the categories held. unused=true leaves out what this organization already used.

Stamp a recipe run so the person sees in the app that it happened.

The standing orders of a brand, saved by a person in the app: each recipe says what to post from (source quotes|trending|manual with source_params, and source_call = the exact request that fetches the content), which template (template.slug for viralhunt_get_template), format, networks, cadence (daily|weekdays|weekly|manual), post_time in the project's timezone (null = the network's best time), caption_brief and last_run_at. Nothing runs on the server: you do the loop (fetch, fill, render, schedule, mark the quote used, then viralhunt_recipe_ran). daily with last_run_at older than today = due. Never run a paused recipe (is_active false).

Append your review to a post in Review: verdict ok|fix|block, a score 0-100, per-topic scores (tos_risk, rights, fake_news, sensationalism, brand, grammar; 100 = clean) plus risk10 (1 safe to 10 breaks a network's terms), image_match and ai_written (0-100), one warning per issue with the policy's code (policy_* / fix_*), the network it concerns and the severity, and a short note on how to fix it, in the post's language. Judge against viralhunt_policy (read it first), network by network; verify claims with viralhunt_search / trending rss. `fix` sends the post back to Drafts with your note (returned: true). The server recalculates the verdict from your scores and warnings with the policy thresholds and keeps the more severe one (verdict, verdict_requested, verdict_reason in the answer). An `ok` sends the post at its time only when the organization sends on OK AND this token may release (owner, admin, or 'their OK publishes' in Team); The note carries the fix (the corrected sentence, the exact link, the short version); say which problem decided the verdict. The server refuses to send on a self review (same USER, not token: the reviewer is its own agent member), a post with no time or under 15 minutes, one edited after the review, or one whose scores sit outside the policy's auto_send thresholds (risk10 > 5, fake_news < 70, image_match < 60: risk_threshold, a person decides), and says why in sent.skipped. Report `sent` as it is. Drafts rows carry project_lang: a post in another language is fix_language. Always pass content_hash from the row you read: if the post changed meanwhile the server answers 409 content_changed with the current hash and writes nothing; read it again.

The reviewer's queue: posts in Review, every project, with no verdict on their current content (never reviewed, or edited after the last verdict). Same rows as viralhunt_drafts. Read viralhunt_policy first, then one viralhunt_review_draft per post.

Flags per collaborator (owner, admin, or a reviewer marked 'Their OK publishes'): for the last days (7 = week, 14 = fortnight, 30 = month), per person or agent who authored posts: reviews, ok / fix / block, flags (a fix or block, or any policy_* / fix_* warning), codes (how many of each rule, e.g. fix_doi), avg_risk10 and last_flag_at. The Team page shows the same table.

Publish now, schedule, or (default when the user did not ask to publish right now) leave a DRAFT of a post on a project's connected accounts. Ask the user before publishing or scheduling: it posts to real accounts. Verify content first: never fake news, copyrighted media or spam. Never use another page's text as the copy or its branded picture as the post's picture: the picture comes from the organization's templates (viralhunt_get_template), either rendered by you and passed in media, or passed as `design` with draft=true so the app renders it when a person approves. Returns {id, status, results, warnings, review_url}: status processing|scheduled|review|draft|partial|failed; results keyed by account id carry each network's own reason when it refused. Two stages sit before sending: Drafts (being worked on) and Review (complete, dated, waiting for an owner or admin). Say which one the post is in. The working agreement: a post the user asks for goes to Drafts COMPLETE (text, image, accounts, tentative time, the project they named; no picture with rights = the organization's template with text only), never to Review unless asked. Hand it over in one five-line message: id and project_name, the url the answer gives (never compose a link), the angle, what you verified and the source, the decision you need. Everything else goes in author_notes. The Drafts page shows one project at a time (name the project); media_removed after a week is retention. A picture made on a template is complete only with its design in the post (pass the PNG in media AND design): a PNG alone is a flat file nobody can edit in the app; the answer says picture_editable: false and viralhunt_update_post with design repairs it. Every picture is made on one of the organization's templates; when none fits, CREATE one (viralhunt_upsert_template, the owner's 'Creates templates' tick) and use it.

Search one keyword across every network at once (or a chosen subset) and get one merged, ranked list: each row normalized to platform, id, title, description, post_url, thumbnail_url, author_name, author_handle, engagement_score, stats, growth_24h, created_at, plus the network's full row under raw. sources[] says per network how many posts matched (total), so you can tell the user where the topic lives and where the corpus holds nothing (total 0 = say so, never invent posts). All words must appear, in any order. Use viralhunt_trending when the user wants ONE network with its own sorts and paging.

Engagement of the published posts as the networks report it back: by_network, by_project and top_posts (with permalinks). ready=false means nothing collected yet. Use it to answer 'what worked' and to find more like the winners (viralhunt_search on the winning topic); never invent a number.

Move a draft to Review once it is complete (a body or media, and at least one account): it waits there for an owner or admin to authorize it. now=true clears the time (it goes out when authorized); scheduled_at sets one; neither keeps the draft's own. Nothing is sent.

Refresh the status of this organization's posts from the networks (call before viralhunt_get_post when the answer matters). Returns how many rows were re-read.

List the user's projects/brands and the connected social accounts you can publish to in each. Also returns needs_reconnect (expired connections: not targets until a person reconnects them in the app; name the network before publishing), media_limits per network (image bytes: bigger ones are re-encoded to fit; video bytes and seconds: a bigger or longer video is refused for that network only, with the numbers; text length), each project's lang and translates_to (linked projects in another language), and must_draft: '' = this token may publish directly; 'role' = a member or agent token: every post waits in Drafts for an owner or admin whatever draft says; 'review_mode' = the organization reviews every post. Read it before promising 'published'. Each project carries voice: the owner's playbook for that brand (audience, tone, hooks, structure, per-network versions, what it never says, verification). Read it before writing anything for that project and follow it over the general rules; when empty, offer to draft one from the brand's best posts for the owner to paste on the Projects page. And complete means every network's copy: for every account whose text_limit the body exceeds (X 280, Bluesky 300, Threads 500), its own short copy in overrides in the same create, never a cut.

Top hashtags from the captions of the posts we hold, per network or across all, optionally filtered to tags containing a word. Each row carries posts (sample size), total_engagement and per_post (the number to compare: a tag used less but hitting harder). `window` is all-time over the corpus with updated_at (there is no per-day hashtag history; say so if asked for 'this week'). Pass `hashtag` to get one tag broken down by network with its top posts.

Make the translated draft of a post (a draft or one already sent) in a linked project that publishes in another language. The app adapts the copy, the first comment, the per-network copies, the thread and the TEXT variables of a design (hashtags in the new language; links, mentions, numbers and names kept): do not translate yourself. A design keeps its picture and the answer carries needs_png=true with render {html, css, format}: render it, store the PNG with viralhunt_update_post {id, png}, then approve if wanted. A plain picture (no template) stays unless `image` hands the translated one. The same translation twice is refused. The texts come back without em dashes, and for every network of the target project whose limit the translated body passes (X 280, Bluesky 300, Threads 500) a short copy is written as that network's override: `shortened` lists them (network, limit, full length, short length) and `overrides` carries the copies. One brand, two languages: link the projects once (Projects → Also publish translated in…), work in one project, and the other language comes out of this call or of `translations` on viralhunt_approve_draft. Never write the second language by hand.

Find trending/viral posts on a social network, ranked by viral score (engagement velocity). Sources: tiktok, instagram, x, facebook, pinterest, bluesky, douyin, reddit, mastodon, tumblr, hackernews, and rss (news articles from 230 feeds plus articles discovered through social links, each with Facebook/Reddit/Bluesky/Hacker News/comment signals). Each post carries growth_24h when we hold at least two readings of it: {from, to, delta, percent, hours, measured_at, samples}. Read it carefully: growth_24h null means 'we cannot say', NOT zero (Facebook and Pinterest never carry it); delta 0 with samples >= 2 means measured and unchanged (flat), not missing; `hours` is the REAL window between the two readings (the newest reading at least 20h older than the latest, or the oldest one when the post is younger than that), so it is often under 24: quote it, never assume 24, and say 'in 24h' only when `full_window` is true; `percent` is null when `from` is under 100 (from zero or from a handful of interactions a percentage is noise) while `delta` always holds the absolute change. A high delta over few hours is what 'going viral right now' looks like.

Trending sounds/audio on TikTok, Instagram Reels and Douyin, ranked by the engagement of the posts that used them, cross-network sounds first. A sound is listed only when several different accounts used it (one account's audio is a voiceover, not a trend). Each sound carries networks{tiktok|instagram|douyin: posts, creators, eng, per_post}, cross (on more than one network) and stronger (tiktok|instagram|even, per post) when both sides are measured. Pass `slug` for one sound with the posts that used it. Window is all-time over the corpus.

Edit a post. A DRAFT can be changed freely by its author, an owner or an admin (body, media, overrides, first_comment, targets, scheduled_at, design, and png: the a reviewer marked 'Their OK publishes' may change only overrides (a per-account short copy), kind, and the texts inside the image (design_fields {variable key: text}, never a picture variable or caption; with its png) on someone else's post). design_fields works on posts made on a template only (a flat picture answers no_design); without png the old render leaves (needs_png + render in the answer). overrides is MERGED per account: send only the accounts you change, a key set to null removes that account's copy, overrides_replace: true replaces the whole map; rendered picture of its design as a data:image/png;base64 URL, which becomes the post's first picture). A SCHEDULED post can be edited only while status is 'scheduled' and more than 5 min before publish. Only the fields you send change; the project cannot be changed. Check status with viralhunt_get_post first; on a 409 error re-fetch instead of retrying.

Create or edit a content template (layout HTML/CSS + variable manifest). Editing a curated/global template CLONES it into the org's own copy — the global is never modified. Every {{placeholder}} in the html must be declared in variables, or the call is rejected. Owners and admins, or a member/agent the owner ticked 'Creates templates' (they edit only the templates they created). A template is html, css and images, never code: scripts, iframes, forms, event handlers and javascript: URLs are removed and listed in `removed`; data:font/ and data:image/ are accepted. Coloured words and a headline that fits need no script: put data-highlight="{{highlight}}" on the headline (the listed words get <span class="hl">, your css styles .hl), data-fit="28" (or data-fit-lines="4") on a block whose text must shrink to fit, and the platform appends its runtime (runtime_added: true), which also sets data-vh-ready. On update you may send only the fields that change. Then viralhunt_get_template with preview=true shows how it came out.