Hermoso — MCP, CLI & Skills

Hermoso — MCP, CLI & Skills

Drive Hermoso — the AI ad studio — from any AI agent: Claude Code, Claude.ai, Cursor,Codex, or your own scripts. Research the ads already winning in a market, plan a creative, and generate finishedimage & video ads (your real product composited in, copy + CTA included) — all overMCP tools, a CLI, or installable Claude skills.

Instant: the hosted Claude.ai connector

Paste https://app.hermoso.ai/mcp into Claude → Settings → Connectors → Add custom connector, approve withyour Hermoso account, done — the full studio toolset with your saved brand context, billed to your plan.

Quickstart for Claude Code / Cursor / scripts (2 minutes)

1. Get an account at app.hermoso.ai — free tier included; plans & credits are thesame ones the web Studio uses.
2. Create an agent key: app.hermoso.ai → Settings → Agents & API → Create API key (hmk_…).
3. Connect — no clone needed, npx runs the published hermoso package (Claude Code shown; any MCP client works):

claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp

Your agent now has the full studio with your workspace's context: the brand profile, products, logos andlearned memory you set up in the web app apply automatically (get_brand shows what's saved; omit brand inplan_ad/plan_variations to use it). Renders bill your Hermoso credits — same prices as the Studio.

1. MCP server (stdio) — Claude Code / Cursor / Codex

hermoso mcp runs a stdio MCP server exposing the full studio toolset (40+ tools). The published hermosopackage means no clone — npx -y hermoso mcp fetches and runs it:

claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp

Cursor / Codex — add to mcp.json (Codex uses the TOML equivalent):

{ "mcpServers": { "hermoso": { "command": "npx", "args": ["-y", "hermoso", "mcp"],
  "env": { "HERMOSO_API_BASE": "https://app.hermoso.ai", "HERMOSO_TOKEN": "<your token>" } } } }

Then ask your agent: “Generate an image ad with Hermoso.”

Tools (40+): research/ad-spy (find_competitors, pull_competitor_ads, research_ads, search_meta_ads,search_google_ads, search_linkedin_ads, search_tiktok, search_instagram, search_youtube, search_reddit,search_threads, scrapecreators_fetch), plan → generate → finish (plan_ad, plan_variations, generate_image,generate_video, generate_avatar, render_ad, make_template_ad, stitch_video, reframe_video,upscale_video, dub_video, change_voice, recast_motion, remix_static, finish_video, fix_beat),brand + account (get_brand, list_brands, use_brand, draft_brand, list_product_photos, set_product_image,hermoso_capabilities, hermoso_credits, buy_credits), and analysis/jobs (analyze_video, score_ad,check_ad_policy, competitor_teardown, mine_angles, get_job, list_jobs, get_skill, list_skills,fetch_asset). Call hermoso_capabilities first — it returns valid model ids and per-render credit costs;tools/list is the authoritative current set. Render jobs queue server-side and poll to completion, returning aserved URL.

2. CLI — the token-cheap path for terminal agents

bin/hermoso.mjs mirrors the tools as subprocess commands, so an agent can shell out instead of carrying a fattool manifest.

npm install -g .                                   # installs `hermoso`
hermoso capabilities                               # valid model ids + costs (run first)
hermoso create --brand "YourBrand" --product "your best-selling product" --format image
hermoso generate image --prompt "…" --ref ./product.png --wait
hermoso generate video --prompt "…" --duration 8 --wait
hermoso competitors yourbrand.com
hermoso research "Liquid Death’s longest-running ads"

Add --json to any command for machine output.

3. Claude skills — slash commands that wrap the CLI

skills/ holds four installable skills: hermoso-generate, hermoso-ad-from-brand,hermoso-product-photoshoot, hermoso-research.

cp -r skills/* ~/.claude/skills/

Then invoke /hermoso-ad-from-brand an ad for yourbrand.com — our hero product.

Configuration

mcp/http.mjs is the hosted remote-connector transport (paste-a-URL into Claude.ai → Connectors). It ships inthis repo for transparency and refuses to mount without authenticated identity — no anonymous spend, ever.

License

MIT © Hermoso