Hermoso — MCP、CLI 与技能

从任何 AI 代理运行你的整个营销运营：Claude Code、Claude.ai、Cursor、Codex 或你自己的脚本。研究市场中已经获胜的广告，生成成品图片和视频广告（合成你的真实产品，包含文案和 CTA），发布到你自己的社交渠道，并构建和管理背后的广告活动——全部通过 MCP 工具、CLI 或可安装的 Claude 技能实现。

718 个工具。 tools/list 始终是权威集合；hermoso_capabilities（免费）返回实时模型目录，包含每次渲染的确切积分成本以及完整的能力映射。

它连接什么。 广告平台：Meta、Google Ads、TikTok Ads、LinkedIn Ads、Reddit Ads、X Ads、Pinterest Ads、Snapchat Ads、Microsoft Advertising、Apple Search Ads 和 ChatGPT Ads，以及 Google Merchant Center 中的产品 Feed。发布和排期——十个渠道：Facebook、Instagram、Threads、TikTok、YouTube、X、LinkedIn、Pinterest、Bluesky 和 Telegram。消息传递：WhatsApp（你给一个人发消息，所以它不是第十一个发布渠道）。广告研究：Meta、Google 和 LinkedIn 广告库，以及有机 TikTok、Instagram、YouTube、Threads 和 Reddit。分析：Google Analytics 4、Google Search Console 以及每个已连接平台自身的帖子和活动洞察。文件：Google Drive、Sheets、Docs 和 OneDrive。

它不是全有或全无。 研究、创作、发布/排期和广告管理是四个独立的领域——没有工具要求你先使用另一个。发布或排期你已经拥有的创意，而在这里不生成任何内容（upload_file 将任何本地或外部文件转换为 URL，每个发布、排期和广告构建工具都接受）；在你自己的广告账户上使用你自己的创意构建和读取活动；在没有品牌草稿和没有连接渠道的情况下研究竞争对手；或者生成一个文件而不连接任何东西，然后直接下载。使用你需要的部分，或者全部一起使用。

你的代理应该使用哪个界面？

两种形态，正确的选择由你的客户端能做什么决定，而不是我们偏好哪个。

实测差异（2026-08-27，按真实工具定义计数，而非按字节估算）：

CLI 改为按需回答相同的问题，并且只在被询问时：

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

所以终端代理在整个列表在范围内的情况下，大约用 3.4K tokens 到达第一次调用，而对于其中一小部分则需要 182K。tools 和 tools <name> 读取包中捆绑的注册表——无需密钥、无需网络、无需登录——因此代理可以在任何人登录之前浏览整个产品。只有 call 会花费，并且只有它需要一次 hermoso auth login。

同时使用两者也没问题，这也是我们对 Claude Code 的建议。 一次 hermoso auth login 覆盖 CLI 并且让 claude mcp add hermoso -- npx -y hermoso mcp 无需 env 块就能获取密钥，因此代理可以在想要结构化结果时使用原生工具，在想要广度时使用 shell。如果你只想要一个，选择 CLI：它严格覆盖更多。

在支持 shell 的客户端上，连接器仍然是更好的权衡的情况： 一个会话将在一个领域内进行多次调用。enable_tools({groups:['ads']}) 通过一次免费调用开启活动管理，然后工具就是原生的——无需 shell 引号，结构化结果。一次 shell 往返优于为单个工具加载 221K-token 的组；一旦会话在该领域稳定下来，情况就相反了。

Related MCP server: Prizmad

你的代理可以自行注册

没有 Hermoso 账户的代理可以自行配置一个，获取自己的密钥，并在同一会话中开始渲染广告。无需人在浏览器前，无需工单，无需等待。

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

那个 hmk_ 密钥与页面上其他所有内容使用的凭据相同：/v1、MCP 服务器、CLI。将你的客户端指向它，整个表面就打开了。

支付是浏览器能力的代理已经可以自己完成的事情。 结账是 Stripe 自己的托管页面，所以 Chrome 中的 Claude 和类似的客户端今天就可以无人值守地完成它。其他一切都是单击交接：将 checkout_url 发送给持卡人。同样的形态在你运行后也适用：buy_credits 和 upgrade_plan 会生成一个可支付的链接，用于购买更多积分或更大的计划，billing_status 随时读取余额。

代理路径需要付费计划。 任何一个都可以。免费计划是为在 app.hermoso.ai 注册的人准备的，在这里请求它会返回一个说明这一点的拒绝。在支付完成之前不会创建任何内容，所以未付费的注册不会留下账户，也不会产生任何费用。

有一件事仍然需要人，而且值得提前知道。 连接社交或广告账户意味着 OAuth 同意屏幕，而同意屏幕在任何平台上都无法无人值守地完成。list_connectors 显示已连接和未连接的内容。其他一切都在没有浏览器的情况下运行：研究、生成、发布到已连接的渠道、活动构建、报告。

完整的请求和响应形态，以及所有其他端点，都在 app.hermoso.ai/openapi.json 的 OpenAPI 文档中，从挂载路由的同一张表实时提供。

即时：托管的 Claude.ai 连接器

将 https://app.hermoso.ai/mcp 粘贴到 Claude → 设置 → 连接器 → 添加自定义连接器，用你的 Hermoso 账户批准，完成——完整的工具集带有你保存的品牌上下文，计入你的计划。

Claude Code 快速入门（一行）

1. 获取账户 在 app.hermoso.ai — 包含免费层级；计划和积分与 Web Studio 使用的相同。或者完全跳过浏览器，让你的代理通过 POST /v1/signup（上面）在付费计划上自行注册。

2. 运行一行。 你的浏览器会打开一次以登录。无需粘贴任何内容，密钥也不会出现在 .claude.json 中：

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

3. 用你正常的提示词询问你想要什么。Claude Code 会调用工具，或在你的终端中运行 hermoso 命令，具体取决于任务需要。你不需要输入任何一个。

广告活动和分析工具在通过 enable_tools 开启之前不会出现在工具列表中，这保持了列表的简洁。在没有浏览器的机器上，使用 设置 → 代理与 API 中的密钥通过 hermoso auth login --token hmk_… 登录，或者跳过登录并将密钥传递给客户端：

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

托管 URL 在 Claude Code 中也可以使用，但那里是更差的路径，值得知道原因：claude mcp add --transport http hermoso https://app.hermoso.ai/mcp 被接受，然后 claude mcp list 报告 ! Needs authentication，因为客户端不会自行启动 OAuth 流程——你必须打开一个会话，运行 /mcp，找到服务器并按下 Authenticate。在 2026-08-23 针对 Claude Code 2.1.241 测量。

你的代理现在拥有完整的 Studio 以及你工作区的上下文：你在 Web 应用中设置的品牌资料、产品、徽标和学习记忆会自动应用（get_brand 显示已保存的内容；在 plan_ad/plan_variations 中省略 brand 以使用它）。渲染会消耗你的 Hermoso 积分——与 Studio 相同的价格。

1. MCP 服务器（stdio）— Claude Code / Cursor / Codex

hermoso mcp 运行一个 stdio MCP 服务器，暴露完整的工具集。发布的 hermoso 包意味着无需克隆——npx -y hermoso mcp 会获取并运行它。使用 CLI 登录一次，密钥就不会进入任何客户端配置，因为 hermoso mcp 读取存储的 bearer hermoso auth login：

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

Cursor / Codex — 以相同方式登录，然后添加到 mcp.json（Codex 使用 TOML 等效项）。如果你在上面登录了，完全删除 env 块；它用于 CI，因为进程无法读取你的主目录：

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

然后询问你的代理：“用 Hermoso 生成一个图片广告。”

718 个工具涵盖的内容

广告间谍/研究 — find_competitors、competitor_teardown、pull_competitor_ads、research_ads；Meta / Google / LinkedIn 广告库（search_meta_ads、search_google_ads、search_linkedin_ads）；有机社交（search_tiktok、search_instagram、search_youtube、search_reddit、search_threads）；fetch_social_data、mine_angles、analyze_video、check_ad_policy、list_skills / get_skill。

创建 — draft_brand → plan_ad → render_ad（Studio 质量流程：合成文本、清晰语音、音乐、品牌结尾卡片），或 generate_image / generate_video / generate_avatar（UGC 创作者 + 唇形同步）。工作区的已保存演员阵容可重复使用：list_creators 返回每个已保存创作者及其肖像 URL，save_creator 添加一个，delete_creator 删除一个——将肖像重新传递给 generate_avatar / generate_video / recast_motion，同一个人会出现在每个广告中，而不是每次渲染都出现新面孔。 还有 make_template_ad（原生 HTML 广告格式）、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，以及 plan_variations + score_ad 用于扩展和排名。 长度由你设定： 向 plan_ad 传递 durationSeconds，故事板会编写到该长度——适合渲染模型一个片段长度的长度会渲染为单个连续镜头，更长的会从幕中拼接（在 15 秒片段模型上，40 秒 = 15+15+10），绝不会时间压缩。适合一个片段的是模型自身的最大值，而不是固定数字：大多数视频模型将片段限制为 15 秒，而最长片段模型可以在 30 秒内不间断地拍摄，并带有原生同步音频。hermoso_capabilities 是实时列表——时长、分辨率和每个层级的确切积分成本——在 model 中命名该模型是获得它的方式，因为未命名的渲染会由更窄的自动池路由。

原始模型游乐场 —— 完整目录（30+ 图像 / 视频 / 语音 / 写作模型，每个都标注了精确的单次渲染积分成本），没有任何广告包装：generate_image / generate_video（使用 useBrand:false）、generate_voice、generate_text。

发布到您自己的渠道 —— 共十个：Facebook、Instagram 和 Threads（post_to_meta）、TikTok（post_to_tiktok）、YouTube（post_to_youtube + update_youtube_video、youtube_video_insights、评论读取/回复）、X（post_to_x、x_post_metrics、x_post_insights、x_mentions、list_x_dms、send_x_dm）、LinkedIn 个人主页和公司主页（post_to_linkedin、post_to_linkedin_page）、Pinterest（post_to_pinterest + 画板）、Bluesky（post_to_bluesky、delete_bluesky_post、bluesky_post_metrics，以及 list_bluesky_convos / read_bluesky_dm / send_bluesky_dm）和 Telegram（post_to_telegram、delete_telegram_message、list_telegram_chats）。schedule_post / list_scheduled / cancel_scheduled 为您提供覆盖上述全部渠道的统一内容日历。upload_file 可导入任何外部或本地媒体，不仅限于 Hermoso 渲染的素材。 X 发帖按 API 调用计费积分（X 按请求收费）；包含链接的帖子费用是不含链接帖子的 13 倍。 *有所保留，并且明确点名而非隐藏：*Google Business Profile 已构建完成（post_to_google_business、评论、Q&A、洞察），但未提供 —— Google 按项目对该 API 进行白名单授权，而我们的配额读取为 0 QPM，因此每次调用对每个用户都会返回 403。它存在于 schedule_post 的渠道枚举中，但在入队时会被拒绝。

通过 WhatsApp 与客户沟通 —— 这是消息传递，而非第十一个发布渠道：您是在给一个人发消息，这里没有任何功能会发布到信息流。list_whatsapp_accounts 查找商业账户及其号码，list_whatsapp_templates / create_whatsapp_template / delete_whatsapp_template 管理 Meta 审核的模板，send_whatsapp_message 发送一条消息 —— 需要确认门控，因为它会到达真实手机，且 Meta 会按会话向商家收费。有两个关于 Meta API 的永久性事实限制，而非任何待定事项：Hermoso 不接收 WhatsApp webhook，因此没有可读取的消息历史 —— 它不是收件箱界面，list_inbox 也不覆盖它 —— 并且在客户首次发消息开启的 24 小时窗口之外，WhatsApp 只接受已批准的模板，其他一律拒绝。

投放广告 —— 完整的广告系列树，默认以暂停状态构建，在报告任何内容之前先读回确认，每次预算变更都有确认门控，覆盖十一个平台：Meta、Google Ads、LinkedIn Ads、Reddit Ads、Pinterest Ads、Microsoft Advertising、ChatGPT Ads（OpenAI 的 Advertiser API）、X Ads、TikTok Ads、Snapchat Ads 和 Apple Ads（App Store 上的 Apple Search Ads）。每个平台都有列表 + 报告 + 创建 + 预算/状态工具（例如 list_google_ads_campaigns、google_ads_report、create_google_ads_campaign、set_google_ads_budget、set_google_ads_status）。Snapchat 需要其他平台不需要的一个额外步骤：广告必须指向一个 CREATIVE，而每个 Snapchat 创意都必须携带一个 Public Profile id —— 使用 upload_snapchat_ads_creative 构建它。

填充购物渠道 —— Google Merchant Center 是零售 Performance Max 或 Shopping 广告系列所推广的商品目录（create_google_ads_performance_max_campaign 接受 merchantCenterId），您可以在这里管理它：账户和账户状态、数据源、商品 upsert / 更新 / 删除、按地区库存、配额、用于商品级效果的 merchant_report、通知和转化来源，以及拒批循环 —— list_merchant_issues 说明问题所在，merchant_issue_help 返回 Google 官方记录的修复方案。*促销活动需要商家自行注册 Google 的促销计划；否则 Google 会直接拒绝该子 API。*Microsoft Merchant Center 以相同结构覆盖（商店、目录、商品、问题），用于 Bing Shopping。

衡量广告效果 —— Google Analytics 4 闭环。这里每个其他连接器报告的是广告花费了多少；而这个是报告它带来了什么。analytics_report 按渠道、来源/媒介、广告系列、落地页、国家/地区、设备或日期细分会话、用户、转化和收入，因此 Hermoso 构建的广告系列和它带来的收入可以在同一个对话中呈现。analytics_realtime 显示当前正在访问网站的人。从 list_analytics_properties 开始 —— 这些工具接受数字型 property id，而不是您跟踪代码片段中的 G-XXXXXXXXX 测量 ID，这个工具就是用来解析两者对应关系的。它不仅能读，还能写：create_analytics_key_event 将 GA4 已收集的事件标记为关键事件 —— 这正是使其可作为转化导入 Google Ads 的条件 —— 而 create_analytics_custom_dimension 注册一个事件参数，使报告可以按它进行细分，list_analytics_definitions 显示该 property 已衡量的内容。它使用与 Google Ads、YouTube 和 Drive 相同的 Google 账户登录，但它是独立的连接。 仅 GA4 —— 该 API 没有 Universal Analytics 界面。自定义维度可以归档但永远无法删除，一个 property 最多容纳 50 个事件级自定义维度。

文件 —— Google Drive CRUD（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）和 OneDrive（save_to_onedrive + 完整 CRUD）。

工作区与账户 —— 品牌工作区（list_brands、create_brand、use_brand、update_brand、delete_brand —— 一个账户可持有多个品牌，因此代理机构可以通过这里管理每个客户）、记忆（remember、forget、list_memory）、自定义技能（save_skill、get_skill、list_skills、delete_skill —— 统一的技能库，吸收了旧的 AI-Employee 角色）、团队（list_team、invite_member、remove_member、set_role）、设置（get_settings、update_settings —— 包括每条广告、脚本和方案所使用的语言）、连接器（list_connectors、list_connector_accounts、set_connector_accounts、disconnect_connector）和计费（hermoso_credits、billing_status、buy_credits、upgrade_plan、set_auto_reload），以及用于异步渲染的 list_jobs / get_job。

连接器账户是选定的，而非猜测的。 一个人通常管理多个 Facebook 主页、Google Ads 客户或 LinkedIn 公司主页。只有为品牌勾选的账户才可用 —— 在服务端强制执行，空选择不共享任何内容。关联新账户是唯一一个非无头操作的步骤（它是 OAuth 同意界面，因此用户需要在应用中完成）。

渲染任务在服务端排队并轮询直至完成，返回一个可访问的 URL。

2. CLI —— 面向终端代理的令牌节省路径

bin/hermoso.mjs 将完整的 MCP 工具集暴露为子进程命令，因此代理可以直接 shell 调用，而无需携带庞大的工具清单。

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"

为任何命令添加 --json 以获取机器可读输出。

这些快捷方式是常用路径，而非全部能力。 MCP 服务器拥有的每个工具在这里也都可以访问，包括连接器默认工具列表中未包含的广告系列和数据分析组：

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 走的是与 MCP 服务器相同的处理器、相同的参数验证和相同的确认/消费门控 —— 不存在会漂移的第二套实现。tools 和 tools <name> 读取包内捆绑的注册表，因此无需密钥、无需网络、无需登录。

3. Claude 技能 —— 包装 CLI 的斜杠命令

skills/ 包含四个可安装技能：hermoso-generate、hermoso-ad-from-brand、hermoso-product-photoshoot、hermoso-research。

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

然后调用 /hermoso-ad-from-brand an ad for yourbrand.com — our hero product。

配置

mcp/http.mjs 是托管的远程连接器传输层（将 URL 粘贴到 Claude.ai → Connectors）。它随本仓库一起发布以保证透明性，并且在没有经过身份验证的身份时拒绝挂载 —— 绝不允许匿名消费。

许可证

MIT © Hermoso