Hermoso — MCP, CLI y Skills

Dirige 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 vídeo terminados (tu producto real compuesto, copia + CTA incluidos), publícalos en tus propios canales sociales y crea y gestiona las campañas publicitarias detrás de ellos — todo a través de herramientas MCP, una CLI o skills de Claude instalables.

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

A qué se conecta. Plataformas publicitarias: 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, así que no es un undécimo canal de publicación). Investigación de anuncios: las bibliotecas de anuncios de Meta, Google y LinkedIn, además de TikTok, Instagram, YouTube, Threads y Reddit orgánicos. 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 creatividades que ya tengas 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); crea y lee campañas en tus propias cuentas publicitarias con tu propia creatividad; investiga competidores sin una marca redactada ni un 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 cuál preferimos.

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

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 repertorio en alcance, 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 — así que un agente puede explorar todo el producto antes de que nadie 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 bloque env, así que el agente puede recurrir a una herramienta nativa cuando quiera resultados estructurados y al shell cuando quiera amplitud. Si solo quieres uno, elige la CLI: cubre estrictamente más.

Cuando el conector sigue siendo el mejor intercambio en un cliente con shell: una sesión que va a hacer muchas llamadas a una sola área. enable_tools({groups:['ads']}) activa la gestión de campañas en una sola llamada gratuita y las herramientas pasan a ser nativas — sin comillas de shell, resultados estructurados. Un viaje de ida y vuelta de shell supera a 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.

Related MCP server: Prizmad

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 un humano en un navegador, sin ticket, sin esperas.

# 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 acepta todo lo demás en esta página: /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, así 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 marcha: 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 pedirlo aquí devuelve una negativa que lo dice. Nada se crea hasta que el pago se completa, así que un registro no pagado no deja ninguna cuenta atrá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 publicitaria significa una pantalla de consentimiento OAuth, y una pantalla de consentimiento no se puede completar 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, construcción de campañas, informes.

Las formas completas de solicitud y respuesta, además de 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 → Añadir 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)

1. Obtén una cuenta en app.hermoso.ai — incluye el nivel gratuito; 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).

2. 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

3. 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 publicitarias 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 se acepta, y luego claude mcp list informa ! 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 pulsar 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 renderizados 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 hermoso publicado significa que no hay clon — npx -y hermoso mcp lo descarga 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 portador que hermoso auth login almacena:

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 añade 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 personal:

{ "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, voz 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 añade 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 renderizado. También make_template_ad (formatos de anuncio 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, además de plan_variations + score_ad para expandir y clasificar. La duración es tuya para establecer: pasa durationSeconds a plan_ad y el guion gráfico se escribe para esa duración — una duración que cabe en un clip del modelo de renderizado 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 vídeo 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 coste exacto de crédito de cada nivel — y nombrar ese modelo en model es cómo lo obtienes, ya que un renderizado sin nombre se enruta por un grupo automático más estrecho.

Playground de modelos en bruto — el catálogo completo (más de 30 modelos de imagen / vídeo / voz / escritura, cada uno con su coste exacto en créditos por render) sin ningún marco publicitario: 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, lectura/respuesta de comentarios), 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 único calendario de contenidos sobre exactamente ese conjunto. upload_file permite importar cualquier medio externo o local, no solo los renders de Hermoso. Publicar en X factura créditos por llamada a la API (X cobra por solicitud); una publicación con enlace cuesta 13× más que una sin él. Retenido, y nombrado en lugar de ocultado: Google Business Profile está construido (post_to_google_business, reseñas, Q&A, insights) y no se ofrece — Google permite esa API por proyecto y la nuestra lee 0 QPM, así que cada llamada daría 403 para todos los usuarios. Está en el enum de canales de schedule_post y se rechaza al encolar.

Mensajes a clientes por WhatsApp — mensajería, no un undécimo canal de publicación: escribes 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 y no algo pendiente: Hermoso no recibe webhooks de WhatsApp, así que no hay historial de mensajes que 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 escribe primero, 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 que se informe de nada, con cada cambio de gasto sujeto a confirmación, 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 (p. ej. list_google_ads_campaigns, google_ads_report, create_google_ads_campaign, set_google_ads_budget, set_google_ads_status). Snapchat requiere un paso extra que las demás no: un anuncio apunta a un CREATIVE, y cada creative 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 acepta un merchantCenterId), y lo gestionas desde aquí: cuentas y estado de cuentas, fuentes de datos, alta / actualización / baja 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 dice qué está mal y merchant_issue_help devuelve la solución documentada por el propio Google. Las promociones requieren que el comerciante se haya dado de alta en el programa de promociones de Google; sin ello Google rechaza esa sub-API directamente. Microsoft Merchant Center está cubierto con la misma forma (tiendas, catálogos, productos, incidencias) para Bing Shopping.

Mide lo que lograron los anuncios — Google Analytics 4 cierra el círculo. Todos los demás conectores de aquí informan de lo que un anuncio costó; este es el que informa de 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, de modo que la campaña que Hermoso construyó y los ingresos que generó están en una misma conversación. analytics_realtime muestra quién está en el sitio ahora mismo. Empieza en list_analytics_properties — las herramientas aceptan un id de propiedad numérico, no el ID de medición 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 a 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 su propia conexión. Solo GA4 — la API no tiene superficie de Universal Analytics. Una dimensión personalizada se puede archivar pero nunca eliminar, y una propiedad admite 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 alberga muchas marcas, así 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), ajustes (get_settings, update_settings — incluido el idioma en el que se escriben todos los anuncios, guiones y planes), 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 renders asíncronos.

Las cuentas de conector se eligen, no se adivinan. Una misma persona administra a menudo 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 headless (es una pantalla de consentimiento OAuth, así que el usuario lo hace en la aplicación).

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

2. CLI — la vía de bajo coste en tokens para agentes de terminal

bin/hermoso.mjs expone todo el conjunto de herramientas MCP como comandos de subproceso, de modo que un agente puede invocar el shell en lugar de cargar 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"

Añade --json a cualquier comando para obtener salida en máquina.

Esos atajos son la vía común, no el límite. Todas las herramientas que tiene el servidor MCP también son accesibles aquí, incluidos los grupos de campañas publicitarias y de analítica 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 handler, la misma validación de argumentos y las mismas puertas de confirmación/gasto que usa el servidor MCP — no hay una segunda implementación que pueda divergir. tools y tools <name> leen un registro incluido en el paquete, así que no necesitan clave, ni 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/

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

Configuración

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 — nunca gasto anónimo.

Licencia

MIT © Hermoso