Hermoso: MCP, CLI & Skills

The AI marketing agent with an AI ad generator built in, run from any AI agent: Claude Code, Claude.ai, Cursor, Codex, or your own scripts. Research the ads already winning in a market, generate image & video ads (your real product composited in, copy + CTA included), publish them to your own social channels, and build & manage the ad campaigns behind them, all over MCP tools, a CLI, or installable Claude skills.

1109 tools. tools/list is always the authoritative set; hermoso_capabilities (free) returns the live model catalog with exact per-render credit costs plus the full capability map.

No markup on models on Starter, Pro and Studio. Stop overpaying markups on AI models. Plans: hermoso.ai/pricing.

A Chrome extension too. Hermoso: save and clone ads saves any ad to your swipefile in one click, clones it for your brand, and pulls any company's ads from its website.

Most of it costs nothing. Publishing and scheduling posts, building and managing paid campaigns, analytics and insights, comments and DMs, connectors, profiles and team seats cost no credits on any plan, with no per-post fee and no seat pricing. The Free plan includes 30 posts a month on up to 3 platforms; every paid plan posts without a limit and runs autopilot. Basic ($9.99 a month) is unlimited posting and Autopilot with no monthly credits: it includes the same 250+ free credits as the Free plan, monthly credits start on Starter, and Autopilot spends credits. Credits are spent only on running an AI model (image, video, voice, text, planning, post-production) and on Ad Spy research, and posting an ad you already rendered is never a second charge. The one exception is X (Twitter), where posting and reads bill credits per call because X charges per API request (hermoso_credits prints the exact credits per X post).

What it connects to. Ad platforms: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads, ChatGPT Ads and AppLovin Ads, plus product feeds in Google Merchant Center. Publishing and scheduling — eleven channels: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky, Telegram and Google Business Profile. Messaging: WhatsApp (you message a person, so it is not a twelfth publishing channel) and DM automations on Instagram, Facebook Pages and Messenger, and X (a keyword comment, a DM, a story reply or an ig.me / m.me link gets an automatic reply). Ad research: the Meta, Google and LinkedIn ad libraries plus organic TikTok, Instagram, YouTube, Threads and Reddit. Analytics: Google Analytics 4, Google Search Console and every connected platform's own post and campaign insights. Files: Google Drive, Sheets, Docs and OneDrive.

It is not all-or-nothing. Research, creation, publishing/scheduling and ads management are four independent areas — no tool requires that you used another one first. Publish or schedule creative you already have and generate nothing here (upload_file turns any local or external file into a URL every publish, schedule and ad-build tool accepts); build and read campaigns on your own ad accounts with your own creative; research competitors with no brand drafted and no channel connected; or generate a file with nothing connected at all and just download it. Use the one piece you need, or all of it together.

Install in one command

This repo is a plugin marketplace, a Gemini CLI extension and a skills package at once, so a coding agent takes Hermoso in one line. Every install brings the same five skills (hermoso-research, hermoso-generate, hermoso-ad-from-brand, hermoso-product-photoshoot, hermoso-marketing), and the skills drive the hermoso CLI through npx. No tool list is loaded into your session: a CLI command costs nothing until it runs, and it reaches every tool. The first time, your agent runs npx -y hermoso auth login, which opens a browser to sign in.

Claude Code:

claude plugin marketplace add hermoso-ai/hermoso && claude plugin install hermoso@hermoso

Inside a session the same thing is /plugin marketplace add hermoso-ai/hermoso then /plugin install hermoso@hermoso.

Codex CLI (it reads the same marketplace file):

codex plugin marketplace add hermoso-ai/hermoso && codex plugin add hermoso@hermoso

Gemini CLI:

gemini extensions install https://github.com/hermoso-ai/hermoso

Grok (xAI) comes in three shapes, and each one connects differently:

• grok.com and the Grok apps take the hosted connector: open Plugins → Connectors → New Connector → Custom (or go straight to grok.com/connectors), paste https://app.hermoso.ai/mcp and sign in with your Hermoso account.

• Grok Bot: add the Hermoso Marketing Bot template. It arrives wired to Hermoso and asks for a key, which you create in the app under MCP & CLI → Terminal & API keys.

• Grok Build, xAI's terminal agent, runs a local MCP server. Sign in once, then add it:

  npx -y hermoso auth login
  grok mcp add hermoso -- npx -y hermoso mcp
  

Cursor, OpenCode, GitHub Copilot, Windsurf and about 75 more agents, through the open skills installer:

npx skills add hermoso-ai/hermoso

It asks which agents to install into; -a opencode (or cursor, github-copilot, windsurf) picks one, and --skill hermoso-research installs a single skill. VS Code agent plugins can also take this repo whole: run Chat: Install Plugin From Source and paste https://github.com/hermoso-ai/hermoso.

ChatGPT and Claude.ai run in a browser and cannot run a CLI, so they use the hosted connector instead (see below). The ChatGPT desktop app and ChatGPT workspace admins can also read this repo's .claude-plugin/marketplace.json, which installs the skills.

No browser on the machine? Create a key in the app under MCP & CLI and run npx -y hermoso auth login --token <key>.

On a server, a CI job or an agent gateway that calls Hermoso many times a day, install it once (npm i -g hermoso) and call hermoso directly. npx asks the npm registry about the package on every run, and a busy machine can be rate-limited by npm. If the CLI ever says an HTTP error "did not come from Hermoso", something on your side (a proxy, a firewall or the gateway) refused the request before it reached us.

Which surface should your agent use?

Two shapes, and the right one is decided by what your client can do, not by which we prefer.

| Your client | Use | Why | | --- | --- | --- | | Runs in a browser: Claude.ai, ChatGPT, Claude Desktop | the hosted connector https://app.hermoso.ai/mcp | It cannot spawn a local process, so a URL is the only shape it has. Nothing to install, no key to paste, and the full toolset arrives with your saved brand context. This is the right answer for these clients, not a lesser one. | | Can run a shell: Claude Code, Codex, Gemini CLI, Cursor, Cline, OpenClaw, Hermes, your own scripts | the one-command install above, or the CLI itself (npm install -g hermoso) | A tool manifest is loaded into every session whether or not a tool is called. A shell command costs nothing until it runs, and it reaches every tool rather than the default roster. |

The CLI answers the questions a tool manifest would, on demand and only when asked:

npx -y hermoso tools --search reddit   # every matching tool, name + one line
npx -y hermoso tools plan_ad           # one tool's full argument schema
npx -y hermoso call plan_ad --json '{"product":"…"}'   # run it

tools and tools <name> read a registry bundled in the package (no key, no network, no sign-in), so an agent can browse the entire product before anyone signs in. Only call spends, and only that needs hermoso auth login once.

Want the tools in your coding agent's own list as well? That is the MCP server, and it is optional. One hermoso auth login covers the CLI and lets claude mcp add hermoso -- npx -y hermoso mcp pick the key up with no env block, so the agent can reach for a native tool when it wants structured results and shell out when it wants breadth. It costs context in every session, so add it when a session settles into one area and makes many calls there; enable_tools({groups:['ads']}) then turns campaign management on in a single free call.

Your agent can sign itself up

An agent with no Hermoso account can provision one, get its own key, and be rendering ads in the same session. No human at a browser, no ticket, no waiting.

# 1. Start a signup. This call takes no credential, because the credential is what it creates.
curl -sX POST https://app.hermoso.ai/v1/signup \
  -H 'content-type: application/json' \
  -d '{"plan":"pro","period":"mo","email":"you@yourcompany.com"}'
# -> { "id": "cs_...", "checkout_url": "https://checkout.stripe.com/...", "claim_token": "hsc_...", "email": { "address": "you@yourcompany.com", "verified": false } }
# email = the human behind the account. A verification link goes there; the account works before it is clicked.
# It is a contact mailbox only, never a sign-in. GET /v1/account/email reports the state; POST /v1/account/email/resend re-sends or changes it.

# 2. Pay at checkout_url. Store claim_token first: it is returned only in that response.

# 3. Claim it. Poll until status is "ready".
curl -sX POST https://app.hermoso.ai/v1/signup/cs_.../claim \
  -H 'content-type: application/json' \
  -d '{"claim_token":"hsc_..."}'
# -> { "status": "ready", "api_key": "hmk_...", "credits": 3000 }

That hmk_ key is the same credential everything else on this page takes: /v1, the MCP server, the CLI. Point your client at it and the full surface is open.

Paying is something a browser-capable agent can already do itself. Checkout is Stripe's own hosted page, so Claude in Chrome and clients like it complete it unattended today. Everything else is a one-click handoff: send checkout_url to whoever holds the card. The same shape covers you later, once you are running: buy_credits and upgrade_plan mint a ready-to-pay link for more credits or a bigger plan, and billing_status reads the balance any time.

An agent with its own payment credential can pay with no human at all. POST /api/billing/machine-payment with {"packId": "pack-1k"} answers HTTP 402 carrying a WWW-Authenticate: Payment challenge (Stripe, through the Machine Payments Protocol); pay the challenge and retry, and the same credit pack lands on the same balance. GET /api/billing/config lists the packs under machinePayments. Same packs, same prices, no per-call billing.

The agentic path takes a paid plan. Any of them. The free plan is there for a person signing up at app.hermoso.ai, and asking for it here returns a refusal that says so. Nothing is created until the payment completes, so an unpaid signup leaves no account behind and charges nothing.

One thing still wants a person, and it is worth knowing up front. Connecting a social or ad account means an OAuth consent screen, and a consent screen cannot be completed headlessly on any platform. list_connectors shows what is already connected and what is not. Everything else runs with no browser at all: research, generation, publishing to a channel that is already connected, campaign builds, reporting.

Full request and response shapes, plus every other endpoint, are in the OpenAPI document at app.hermoso.ai/openapi.json, served live from the same table that mounts the routes.

Instant: the hosted Claude.ai connector

Paste https://app.hermoso.ai/mcp?src=readme into Claude →