Hermoso

Hermoso: AI marketing agent and AI ad generator for Claude, ChatGPT and Cursor (MCP server, CLI and 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.

What it does

• Meta Ads MCP server. Build, read and manage Facebook and Instagram campaigns, ad sets, ads, audiences and insights from your agent, preview an ad per placement, and estimate reach before you spend. New campaigns are created paused.
• Google Ads MCP. Search and Performance Max campaigns, ad groups, keywords and keyword ideas, assets, conversion actions, budgets and reports.
• TikTok Ads MCP, and the same campaign tools for LinkedIn Ads, Reddit Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, X Ads, Apple Ads and ChatGPT Ads.
• AI ad generator API. Image, video and UGC avatar ads with your real product, copy and CTA, from render_ad, generate_image and generate_video, the CLI, or the REST API at /v1 (OpenAPI).
• Ad spy. Search the Meta, Google and LinkedIn ad libraries and organic TikTok, Instagram, YouTube, Reddit and Threads, and turn a competitor's longest-running ads into angles you can use.
• Posting. Post and schedule to your own social channels, then read each post's results. The channel list is under *What it connects to* below.

Set up in Claude, ChatGPT or Cursor

Claude (claude.ai, Claude Desktop): Customize → Connectors → Add → *Add custom connector*, paste the URL below, choose Sign in now under Authentication, then Add and Connect.

https://app.hermoso.ai/mcp

Claude Code:

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

ChatGPT: turn on Developer mode once (Settings → Security and login), then Plugins → ＋ → Create app → Create MCP App. Paste https://app.hermoso.ai/mcp as the Server URL, choose OAuth, leave the advanced OAuth settings empty, and press Create.

Cursor:

npx skills add hermoso-ai/hermoso -a cursor && npx -y hermoso auth login

Or add the MCP server to Cursor's mcp.json after npx -y hermoso auth login:

{ "mcpServers": { "hermoso": { "command": "npx", "args": ["-y", "hermoso", "mcp"] } } }

Codex, Gemini CLI, Grok and the rest are in Install in one command.

Examples

Ask in your own words. The agent picks the tools:

• "Pull the longest-running Meta ads for allbirds.com and tell me the three angles they keep paying for."
• "Make a 15-second UGC video ad for our product in 9:16, with a voiceover and captions."
• "Make four static ads for the new collection, one per Instagram placement."
• "Build a Meta Ads campaign for this video with the daily budget I give you, leave it paused, and show me the preview."
• "Compare last week's Google Ads and Meta Ads results and tell me what to pause."
• "Schedule this video to TikTok, Instagram Reels and YouTube Shorts for Tuesday at 9am."

1182 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 10 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 — fifteen channels: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky, Telegram, WordPress, Discord, Slack, Whop and Google Business Profile. Messaging: WhatsApp (you message a person, so it is not a sixteenth 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 .

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.

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 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","e