Hermoso

Ejecuta toda una operación de marketing desde tu agente de IA: investiga los anuncios que ya están ganando, genera anuncios de video e imagen terminados, publica en 10 canales sociales y gestiona campañas en 11 plataformas de anuncios.

GitHubPrueba este MCPPatrocinado

Documentación

Hermoso — MCP, CLI y Skills

Ejecuta toda tu operación de marketing desde cualquier agente de IA: Claude Code, Claude.ai, Cursor, Codex, o tus propios scripts. Investiga los anuncios que ya están ganando en un mercado, genera anuncios de imagen y video terminados (tu producto real compuesto, copia + CTA incluidos), publícalos en tus propios canales sociales, y construye y gestiona las campañas de anuncios detrás de ellos — todo a través de herramientas MCP, una CLI, o skills instalables de Claude.

718 herramientas. tools/list es siempre el conjunto autoritativo; hermoso_capabilities (gratis) devuelve el catálogo de modelos en vivo con costos exactos de crédito por renderizado más el mapa completo de capacidades.

A qué se conecta. Plataformas de anuncios: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads y ChatGPT Ads, además de feeds de productos en Google Merchant Center. Publicación y programación — diez canales: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky y Telegram. Mensajería: WhatsApp (le envías un mensaje a una persona, por lo que no es un undécimo canal de publicación). Investigación de anuncios: las bibliotecas de anuncios de Meta, Google y LinkedIn más TikTok orgánico, Instagram, YouTube, Threads y Reddit. Analítica: Google Analytics 4, Google Search Console y los insights de publicaciones y campañas de cada plataforma conectada. Archivos: Google Drive, Sheets, Docs y OneDrive.

No es todo o nada. Investigación, creación, publicación/programación y gestión de anuncios son cuatro áreas independientes — ninguna herramienta requiere que hayas usado otra primero. Publica o programa creativos que ya tienes y no generes nada aquí (upload_file convierte cualquier archivo local o externo en una URL que toda herramienta de publicación, programación y construcción de anuncios acepta); construye y lee campañas en tus propias cuentas de anuncios con tu propio creativo; investiga competidores sin una marca redactada y sin canal conectado; o genera un archivo sin nada conectado y simplemente descárgalo. Usa la pieza que necesites, o todo junto.

¿Qué superficie debería usar tu agente?

Dos formas, y la correcta se decide por lo que tu cliente puede hacer, no por lo que preferimos.

Tu cliente	Usa	Por qué
Se ejecuta en un navegador — Claude.ai, ChatGPT, Claude Desktop	el conector alojado `https://app.hermoso.ai/mcp`	No puede iniciar un proceso local, por lo que una URL es la única forma que tiene. Nada que instalar, ninguna clave que pegar, y el conjunto completo de herramientas llega con tu contexto de marca guardado. Esta es la respuesta correcta para estos clientes, no una inferior.
Puede ejecutar un shell — Claude Code, Cursor, Codex, Cline, OpenClaw, Hermes, tus propios scripts	la CLI, `npm install -g hermoso`	Un manifiesto de herramientas se carga en cada sesión ya sea que se llame a una herramienta o no. Un comando de shell no cuesta nada hasta que se ejecuta, y llega a todas las herramientas en lugar del roster predeterminado.

La diferencia medida (2026-08-27, contada como definiciones de herramientas reales en lugar de estimada por bytes):

	herramientas en rango	cargadas por sesión
Conector alojado, roster predeterminado	306	181,713 tokens
Conector alojado, `?tools=all`	718	472,062 tokens
Servidor stdio (`npx -y hermoso mcp`)	306	181,713 tokens
CLI	las 718	0

La CLI responde las mismas preguntas bajo demanda en su lugar, y solo cuando se le pregunta:

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

Así que un agente de terminal llega a su primera llamada en aproximadamente 3.4K tokens con todo el roster en rango, frente a 182K por una fracción del mismo. tools y tools <name> leen un registro incluido en el paquete — sin clave, sin red, sin inicio de sesión — para que un agente pueda explorar todo el producto antes de que alguien inicie sesión. Solo call gasta, y solo eso necesita hermoso auth login una vez.

Ambos a la vez está bien, y es lo que sugerimos para Claude Code. Un hermoso auth login cubre la CLI y permite que claude mcp add hermoso -- npx -y hermoso mcp recoja la clave sin bloqueo de env, para que el agente pueda recurrir a una herramienta nativa cuando quiera resultados estructurados y al shell cuando quiera amplitud. Si solo quieres uno, toma la CLI: cubre estrictamente más.

Cuando el conector sigue siendo el mejor intercambio en un cliente con capacidad de shell: una sesión que va a hacer muchas llamadas a un área. enable_tools({groups:['ads']}) activa la gestión de campañas en una sola llamada gratuita y las herramientas son entonces nativas — sin comillas de shell, resultados estructurados. Un viaje de ida y vuelta al shell supera cargar un grupo de 221K tokens para una sola herramienta; lo contrario es cierto una vez que una sesión se asienta en esa área.

Tu agente puede registrarse solo

Un agente sin cuenta de Hermoso puede aprovisionar una, obtener su propia clave, y estar renderizando anuncios en la misma sesión. Sin humano en un navegador, sin ticket, sin espera.

# 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"}'
# -> { "id": "cs_...", "checkout_url": "https://checkout.stripe.com/...", "claim_token": "hsc_..." }

# 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 }

Esa clave hmk_ es la misma credencial que todo lo demás en esta página acepta: /v1, el servidor MCP, la CLI. Apunta tu cliente a ella y toda la superficie está abierta.

Pagar es algo que un agente con capacidad de navegador ya puede hacer por sí mismo. El checkout es la página alojada de Stripe, por lo que Claude en Chrome y clientes similares lo completan sin supervisión hoy. Todo lo demás es una transferencia de un clic: envía checkout_url a quien tenga la tarjeta. La misma forma te cubre más tarde, una vez que estés en funcionamiento: buy_credits y upgrade_plan generan un enlace listo para pagar por más créditos o un plan más grande, y billing_status lee el saldo en cualquier momento.

El camino agéntico requiere un plan de pago. Cualquiera de ellos. El plan gratuito está ahí para una persona que se registra en app.hermoso.ai, y solicitarlo aquí devuelve una negativa que lo dice. Nada se crea hasta que el pago se completa, por lo que un registro no pagado no deja ninguna cuenta detrás y no cobra nada.

Una cosa todavía quiere a una persona, y vale la pena saberlo de antemano. Conectar una cuenta social o de anuncios significa una pantalla de consentimiento OAuth, y una pantalla de consentimiento no puede completarse sin cabeza en ninguna plataforma. list_connectors muestra lo que ya está conectado y lo que no. Todo lo demás se ejecuta sin navegador: investigación, generación, publicación en un canal que ya está conectado, construcciones de campañas, informes.

Las formas completas de solicitud y respuesta, más todos los demás endpoints, están en el documento OpenAPI en app.hermoso.ai/openapi.json, servido en vivo desde la misma tabla que monta las rutas.

Instantáneo: el conector alojado de Claude.ai

Pega https://app.hermoso.ai/mcp en Claude → Configuración → Conectores → Agregar conector personalizado, aprueba con tu cuenta de Hermoso, listo — el conjunto completo de herramientas con tu contexto de marca guardado, facturado a tu plan.

Inicio rápido para Claude Code (una línea)

Obtén una cuenta en app.hermoso.ai — plan gratuito incluido; los planes y créditos son los mismos que usa el Studio web. O salta el navegador por completo y deja que tu agente se registre solo en un plan de pago con POST /v1/signup (arriba).
Ejecuta una línea. Tu navegador se abre una vez para iniciar sesión. Nada que pegar, y ninguna clave termina en .claude.json:

npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcp

Pide lo que quieras, en tus indicaciones normales. Claude Code recurre a una herramienta, o ejecuta el comando hermoso en tu terminal, lo que el trabajo necesite. Tú no escribes ninguno.

Las herramientas de campañas de anuncios y analítica permanecen fuera de la lista de herramientas hasta que las actives con enable_tools, lo que la mantiene pequeña. En una máquina sin navegador, inicia sesión con hermoso auth login --token hmk_… usando una clave de Configuración → Agentes y API, o salta el inicio de sesión y pasa la clave al cliente en su lugar:

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

La URL alojada también funciona en Claude Code, pero es el peor camino allí y vale la pena saber por qué: claude mcp add --transport http hermoso https://app.hermoso.ai/mcp es aceptado, y luego claude mcp list reporta ! Needs authentication porque el cliente no iniciará el flujo OAuth por sí mismo — tienes que abrir una sesión, ejecutar /mcp, encontrar el servidor y presionar Autenticar. Medido contra Claude Code 2.1.241 el 2026-08-23.

Tu agente ahora tiene el estudio completo con el contexto de tu espacio de trabajo: el perfil de marca, productos, logotipos y memoria aprendida que configuraste en la aplicación web se aplican automáticamente (get_brand muestra lo que está guardado; omite brand en plan_ad/plan_variations para usarlo). Los renders se facturan a tus créditos de Hermoso — los mismos precios que el Studio.

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

hermoso mcp ejecuta un servidor MCP stdio que expone el conjunto completo de herramientas. El paquete publicado hermoso significa sin clonación — npx -y hermoso mcp lo obtiene y lo ejecuta. Inicia sesión una vez con la CLI y ninguna clave entra en ninguna configuración de cliente, porque hermoso mcp lee el bearer hermoso auth login almacenado:

npm install -g hermoso && hermoso auth login && claude mcp add hermoso -- npx -y hermoso mcp

Cursor / Codex — inicia sesión de la misma manera, luego agrega a mcp.json (Codex usa el equivalente TOML). Elimina el bloque env por completo si iniciaste sesión arriba; está ahí para CI, donde el proceso no puede leer tu directorio de inicio:

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

Luego pídele a tu agente: "Genera un anuncio de imagen con Hermoso."

Qué cubren las 718 herramientas

Espionaje de anuncios / investigación — find_competitors, competitor_teardown, pull_competitor_ads, research_ads; las bibliotecas de anuncios de Meta / Google / LinkedIn (search_meta_ads, search_google_ads, search_linkedin_ads); social orgánico (search_tiktok, search_instagram, search_youtube, search_reddit, search_threads); fetch_social_data, mine_angles, analyze_video, check_ad_policy, list_skills / get_skill.

Crear — draft_brand → plan_ad → render_ad (el pipeline de calidad del Studio: texto compuesto, habla limpia, música, tarjeta final de marca), o generate_image / generate_video / generate_avatar (creadores UGC + sincronización de labios). El elenco guardado del espacio de trabajo es reutilizable: list_creators devuelve cada creador guardado con su URL de retrato, save_creator agrega uno, delete_creator elimina uno — vuelve a pasar un retrato a generate_avatar / generate_video / recast_motion y la MISMA persona protagoniza cada anuncio, en lugar de una cara nueva en cada render. También make_template_ad (formatos de anuncios HTML nativos), make_explainer, product_sizzle, make_thumbnail, remix_static, recast_motion, reframe_video, upscale_video, dub_video, change_voice, finish_video, fix_beat, stitch_video, clip_video, post_edit, más plan_variations + score_ad para expandir y clasificar. La duración es tuya para establecer: pasa durationSeconds a plan_ad y el storyboard se escribe para ella — una duración que cabe en un clip del modelo de render se renderiza como una sola toma continua, más larga se une a partir de actos (en un modelo de clips de 15s, 40s = 15+15+10), nunca comprimida en el tiempo. Lo que cabe en un clip es el máximo del propio modelo, no un número fijo: la mayoría de los modelos de video limitan un clip a 15 segundos y el modelo de clip más largo toma 30 segundos en una sola toma ininterrumpida con audio sincronizado nativo. hermoso_capabilities es la lista en vivo — duraciones, resoluciones y el costo exacto de crédito de cada nivel — y nombrar ese modelo en model es cómo lo obtienes, ya que un render sin nombre se enruta por un grupo automático más estrecho.

Parque de juegos de modelos en bruto — el catálogo completo (30+ modelos de imagen / video / voz / escritura, cada uno con su costo exacto de crédito por render) sin marco de anuncios: generate_image / generate_video con useBrand:false, generate_voice, generate_text. Publica en tus propios canales — diez de ellos: Facebook, Instagram y Threads (post_to_meta), TikTok (post_to_tiktok), YouTube (post_to_youtube + update_youtube_video, youtube_video_insights, comentarios leer/responder), X (post_to_x, x_post_metrics, x_post_insights, x_mentions, list_x_dms, send_x_dm), perfil de LinkedIn y páginas de empresa (post_to_linkedin, post_to_linkedin_page), Pinterest (post_to_pinterest + tableros), Bluesky (post_to_bluesky, delete_bluesky_post, bluesky_post_metrics, además de list_bluesky_convos / read_bluesky_dm / send_bluesky_dm) y Telegram (post_to_telegram, delete_telegram_message, list_telegram_chats). schedule_post / list_scheduled / cancel_scheduled te dan un calendario de contenido único para exactamente ese conjunto. upload_file incorpora cualquier medio externo o local, no solo los renderizados de Hermoso. La publicación en X cobra créditos por llamada a la API (X cobra por solicitud); una publicación con enlace cuesta 13× una sin él. Retenido, y nombrado en lugar de oculto: Google Business Profile está construido (post_to_google_business, reseñas, preguntas y respuestas, estadísticas) y no se ofrece — Google permite esa API por proyecto y la nuestra lee 0 QPM, por lo que cada llamada daría 403 para cada usuario. Está en la enumeración de canales de schedule_post y se rechaza al encolar.

Envía mensajes a clientes por WhatsApp — mensajería, no un undécimo canal de publicación: envías un mensaje a una persona, y nada de esto publica en un feed. list_whatsapp_accounts encuentra la cuenta comercial y sus números, list_whatsapp_templates / create_whatsapp_template / delete_whatsapp_template gestionan las plantillas que Meta revisa, y send_whatsapp_message envía una — con confirmación obligatoria, porque llega a un teléfono real y Meta factura a la empresa por la conversación. Dos límites que son hechos permanentes de la API de Meta más que algo pendiente: Hermoso no recibe webhooks de WhatsApp, por lo que no hay historial de mensajes para leer — no es una superficie de bandeja de entrada y list_inbox no lo cubre — y fuera de la ventana de 24 horas que se abre cuando el cliente envía el primer mensaje, WhatsApp acepta una plantilla APROBADA y nada más.

Gestiona los anuncios — árboles de campaña completos, creados en pausa y leídos antes de informar cualquier cosa, con cada cambio de gasto con confirmación obligatoria, en once plataformas: Meta, Google Ads, LinkedIn Ads, Reddit Ads, Pinterest Ads, Microsoft Advertising, ChatGPT Ads (API de anunciantes de OpenAI), X Ads, TikTok Ads, Snapchat Ads y Apple Ads (Apple Search Ads en la App Store). Cada una tiene herramientas de listar + informar + crear + presupuesto/estado (por ejemplo, list_google_ads_campaigns, google_ads_report, create_google_ads_campaign, set_google_ads_budget, set_google_ads_status). Snapchat requiere un paso adicional que las demás no: un anuncio apunta a un CREATIVO, y cada creativo de Snapchat debe llevar un id de Perfil Público — constrúyelo con upload_snapchat_ads_creative.

Alimenta las superficies de compra — Google Merchant Center es el catálogo que anuncia una campaña minorista de Performance Max o Shopping (create_google_ads_performance_max_campaign toma un merchantCenterId), y lo gestionas desde aquí: cuentas y estado de cuentas, fuentes de datos, inserción/actualización/eliminación de productos, inventario por región, cuota, merchant_report para rendimiento a nivel de producto, notificaciones y fuentes de conversión, además del bucle de desaprobación — list_merchant_issues indica qué está mal y merchant_issue_help devuelve la solución documentada de Google. Las promociones requieren la inscripción del comerciante en el programa de promociones de Google; sin ella, Google rechaza esa sub-API por completo. Microsoft Merchant Center está cubierto con la misma estructura (tiendas, catálogos, productos, problemas) para Bing Shopping.

Mide lo que lograron los anuncios — Google Analytics 4 cierra el ciclo. Cada otro conector aquí informa lo que un anuncio costó; este es el que informa lo que hizo. analytics_report desglosa sesiones, usuarios, conversiones e ingresos por canal, fuente/medio, campaña, página de destino, país, dispositivo o fecha, para que la campaña que Hermoso creó y los ingresos que generó estén en una sola conversación. analytics_realtime muestra quién está en el sitio ahora mismo. Comienza en list_analytics_properties — las herramientas toman un id de propiedad numérico, no el Measurement ID G-XXXXXXXXX de tu fragmento de seguimiento, y esto es lo que resuelve uno a partir del otro. También escribe, no solo lee: create_analytics_key_event marca un evento que GA4 ya recopila como evento clave — que es lo que lo hace importable en Google Ads como conversión — y create_analytics_custom_dimension registra un parámetro de evento para que los informes puedan desglosar por él, con list_analytics_definitions mostrando lo que la propiedad ya mide. Inicia sesión con la misma cuenta de Google que Google Ads, YouTube y Drive, pero es una conexión propia. Solo GA4 — la API no tiene superficie de Universal Analytics. Una dimensión personalizada se puede archivar pero nunca eliminar, y una propiedad contiene 50 de ámbito de evento.

Archivos — CRUD de Google Drive (save_to_drive, list_drive_files, update_drive_file, delete_drive_file, create_drive_folder), Google Sheets (create_sheet, append_to_sheet, read_sheet), Google Docs (create_doc, append_to_doc) y OneDrive (save_to_onedrive + CRUD completo).

Espacio de trabajo y cuenta — espacios de trabajo de marca (list_brands, create_brand, use_brand, update_brand, delete_brand — una cuenta contiene muchas marcas, por lo que una agencia gestiona a cada cliente desde aquí), memoria (remember, forget, list_memory), habilidades personalizadas (save_skill, get_skill, list_skills, delete_skill — la biblioteca única, que absorbió los antiguos personajes de AI-Employee), equipo (list_team, invite_member, remove_member, set_role), configuración (get_settings, update_settings — incluido el idioma en el que se escriben cada anuncio, guion y plan), conectores (list_connectors, list_connector_accounts, set_connector_accounts, disconnect_connector) y facturación (hermoso_credits, billing_status, buy_credits, upgrade_plan, set_auto_reload), además de list_jobs / get_job para renderizados asíncronos.

Las cuentas de conectores se eligen, no se adivinan. Una persona suele administrar varias páginas de Facebook, clientes de Google Ads o páginas de empresa de LinkedIn. Solo las cuentas marcadas para una marca son utilizables — aplicado en el servidor, y una selección vacía no comparte nada. Vincular una cuenta nueva es el único paso que no es sin interfaz (es una pantalla de consentimiento OAuth, por lo que el usuario lo hace en la aplicación).

Los trabajos de renderizado se ponen en cola en el servidor y se consultan hasta completarse, devolviendo una URL servida.

2. CLI — la ruta económica en tokens para agentes de terminal

bin/hermoso.mjs expone todo el conjunto de herramientas MCP como comandos de subproceso, para que un agente pueda ejecutar comandos externos en lugar de llevar un manifiesto de herramientas pesado.

npm install -g hermoso                             # 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"

Agrega --json a cualquier comando para obtener salida de máquina.

Esos atajos son la ruta común, no el límite. Cada herramienta que tiene el servidor MCP también es accesible aquí, incluidos los grupos de campañas publicitarias y análisis que un conector deja fuera de su lista predeterminada:

hermoso tools                          # every tool, grouped, name + one line
hermoso tools --group ads --search reddit   # narrow it
hermoso tools create_meta_campaign     # that tool's full argument schema
hermoso call create_meta_campaign --json '{"name":"…"}'   # run it
hermoso create_meta_campaign --name "…"                   # same thing, shorter

call pasa por el mismo controlador, la misma validación de argumentos y las mismas puertas de confirmación/gasto que el servidor MCP usa — no hay una segunda implementación que pueda desviarse. tools y tools <name> leen un registro incluido en el paquete, por lo que no necesitan clave, red ni inicio de sesión.

3. Habilidades de Claude — comandos de barra que envuelven la CLI

skills/ contiene cuatro habilidades instalables: hermoso-generate, hermoso-ad-from-brand, hermoso-product-photoshoot, hermoso-research.

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

Luego invoca /hermoso-ad-from-brand an ad for yourbrand.com — our hero product.

Configuración

Env	Significado
`HERMOSO_API_BASE`	El origen de la API de Hermoso (predeterminado `https://app.hermoso.ai` — establece `http://localhost:3000` si ejecutas la aplicación tú mismo)
`HERMOSO_TOKEN`	Clave de agente Bearer (`hmk_…`) — requerida contra la aplicación alojada
`HERMOSO_PROFILE`	Id del espacio de trabajo de marca, para cuentas con múltiples perfiles de marca
`HERMOSO_OWNER`	Solo para una marca que otra cuenta compartió contigo (un espacio de trabajo de equipo): el id de la cuenta propietaria. Establécelo junto con `HERMOSO_PROFILE`, y establece `HERMOSO_PROFILE` al profileUuid de ese espacio de trabajo — se rechaza el slug corto de una marca. Ejecuta `list_brands` (o `hermoso list_brands` desde la CLI) para imprimir ambos valores de cada espacio de trabajo al que puedas entrar. El servidor reautoriza el par en cada solicitud, por lo que un valor incorrecto se rechaza, nunca se confía.

mcp/http.mjs es el transporte de conector remoto alojado (pega una URL en Claude.ai → Conectores). Se incluye en este repositorio por transparencia y se niega a montarse sin identidad autenticada — sin gasto anónimo, nunca.