hermosodocs

Hermoso for developers

Hermoso is an AI marketing studio built to be driven by an agent, not only by a person. Research the ads already winning in a market, generate finished on-brand image and video ads, publish them to the brand's own channels, and build and manage the paid campaigns behind them — all from Claude, Cursor, Codex, or your own scripts.

The interface is an MCP server with 301 tools. There are two ways in and they expose the identical toolset: a hosted connector you paste into Claude, and a stdio server you run with npx. A CLI mirrors the core tools for terminal agents that would rather shell out than carry a large tool manifest.

What an agent can actually do

These are shipped capabilities, not a roadmap. Each links to the generated reference for that area.

Ad spy & research

Pull real ads from the Meta, Google and LinkedIn ad libraries and from organic TikTok, Instagram, YouTube, Reddit and Threads. Tear down what makes a competitor's creative work.

Reference →

Creative generation

Plan an ad, then render it: the real product composited in, copy and CTA baked, clean speech, music, a brand end card. Or go straight to the raw model catalog.

Reference →

Publishing & scheduling

Publish organically to Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest and Google Business Profile — immediately or on a cross-channel schedule.

Reference →

Ad campaign management

Whole campaign trees on Meta, Google Ads, Microsoft Advertising, LinkedIn Ads, Pinterest Ads, Reddit Ads and ChatGPT Ads. Everything is created paused.

Reference →

Files & documents

Read and write Google Drive and OneDrive, and build reports and briefs as Sheets and Docs.

Reference →

Workspace & account

Brand workspaces, saved brand memory, reusable on-camera creators, connectors, team, settings, credits and job status.

Reference →

The shape of a session

Almost every useful sequence has the same spine. The workspace already holds the brand's profile, products, logos and learned memory from the web app, so an agent rarely has to describe the brand at all.

hermoso_capabilities          # free — valid model ids, exact credit costs, what is connected
get_brand                     # what we already know about this brand
plan_ad                       # a storyboard authored to your brief and length
render_ad                     # the finished ad (a job; polls to completion)
post_to_meta                  # publish it, or schedule_post to queue it

hermoso_capabilities is deliberately the first call in that list. It is free, and it returns the live model catalog with exact per-render credit costs plus which channels this workspace has connected — so an agent never guesses a model id, never surprises someone with a bill, and never tells a user to connect something this build does not offer.

Brand context is the point

A raw image model gives you a picture. Hermoso gives you an ad, because the workspace carries context an agent would otherwise have to reconstruct every time: the brand's voice, its real product photography, its palette and logo, the creators it has cast before, and what it has learned works. Omit the brand argument on plan_ad and the saved profile applies automatically.

One account holds many brand workspaces, which is how an agency runs several clients through one connection — list_brands, create_brand, use_brand. The workspace an agent key is pinned to is resolved and re-authorised on the server for every single request; it is never read off a header the caller controls.

Is there a REST API?

Not today, and the honest answer is more useful than a placeholder: the MCP server is the programmatic interface, and it is a complete one. If your client speaks MCP — Claude, Cursor, Codex, the Agents SDK, or any of the growing set of MCP clients — you already have everything documented here.

The routes under /api on the app are internal: they are shaped for our own web client, they authenticate with a browser session, they send no CORS headers, and they change frequently. Building against them directly will break. Use MCP or the CLI.

Where to go next