@facelessad/mcp

FacelessAd as MCP tools — let your AI assistant create faceless video ads.

Works with any MCP-speaking harness: Claude Desktop, Claude Code, Cursor, Windsurf, OpenClaw. Twelve tools, each a single call to the FacelessAd API; the tool/style registry lives on the server, so new tools and styles are available the day they ship without updating this package.

Setup (Claude Desktop)

claude_desktop_config.json:

{
  "mcpServers": {
    "facelessad": {
      "command": "npx",
      "args": ["-y", "@facelessad/mcp"],
      "env": { "FACELESSAD_API_KEY": "fa_live_..." }
    }
  }
}

Create a key at https://facelessad.com/developers. OpenClaw users: add the same block under openclaw mcp config and verify with openclaw mcp doctor --probe.

Needs Node 18 or newer. If your harness pins the MCP SDK, it has to be 1.23.0 or newer — that is the first version whose schema conversion understands zod 4, and an older one silently registers the tools with no parameters at all.

There is also a hosted version that needs no install: add https://facelessad.com/mcp as a custom connector in Claude and authorise it with your account. Same thirteen tools, same fields.

Tools

| Tool | What it does | |------|--------------| | facelessad_list_tools | Registry: tools, styles, structures, hooks, durations | | facelessad_create_video | Create an ad; returns an id immediately | | facelessad_get_video | Status + download URL when done | | facelessad_list_videos | Your videos, newest first | | facelessad_estimate | Upper-bound credit cost without creating | | facelessad_balance | Plan + credits | | facelessad_list_brand_kits | Your brands and their ids (for brand_kit_id) | | facelessad_voices | Curated voice pool | | facelessad_list_parts | The parts of a finished video and how each is fixed | | facelessad_regenerate_part | Redo ONE part (clip, image card, graphics block, or a bg-N AI photo background) | | facelessad_regenerate_video | Rebuild the whole video as a new id | | facelessad_render_settings | Re-render a finished video with new caption/audio settings |

Ask for a look of your own and the assistant sends style: "custom" plus custom_style — facelessad_list_tools marks which tools accept it (supports.customStyle). Product Showcase also takes custom_graphics_style for the text layer drawn over the product video.

Videos build in the background (3–10 min); the assistant polls facelessad_get_video. You are only charged for steps that succeed.

2.4.0 — quality

facelessad_create_video takes quality: "highest" on motion-graphics and saas-ui-ad: after the graphics are rendered, an AI reviewer watches the preview for text cut off at the edges, arrows and pointers aimed at the wrong thing, and motion glitches. Up to three graphics blocks are fixed and the result is verified before the final render. Flat extra price with the fixes included (facelessad_list_tools → quality_review.credits); facelessad_get_video reports the findings under qualityReview. An error on other tools, never ignored.

2.3.0 — visual_direction_refine

facelessad_create_video takes visual_direction_refine on animated-ad and music-video: a preset id (metaphoric, realistic, dramatic, calm, playful, dark, bright, magical — facelessad_list_tools returns them under visual_direction_refine.presets) or your own instruction up to 300 characters. It reshapes how the visual story is told, not how it looks, and is applied on top of visual_direction if given, otherwise on the generated one. Free of charge; an error on other tools, never ignored.

layout (same two tools) picks the card layout — A, HA, AC, HAC, AIA, HAIA, AIAC, HAIAC. Hook and CTA cards you chose always stay; the data card is dropped when the video is too short, and the response says so (layout.applied, layout.notice). facelessad_list_tools lists them.

1.2.0 — text files as materials + agent skill

The package now ships SKILL.md — the same agent skill as @facelessad/cli — so MCP-less agents can operate FacelessAd through the CLI, and MCP users have a reference of every operation in one file.

materials accepts two new fields on facelessad_create_video and facelessad_estimate:

• text_url — a direct link to a raw text file (GitHub raw README, gist, docs export). The server fetches it as-is; use landing_page_url for HTML pages instead.
• file_id — the id of a text file uploaded earlier with POST /api/v1/files (kept 90 days, private to the account).

Long text is no longer silently cut at ~8000 characters: it is condensed server-side in a way that keeps the material's own details, numbers and voice, so a README and a blog post still produce different videos. The hard ceiling is 200 000 characters (materials_too_long). Paste whole release notes, a blog post, or product JSON straight into text.

1.1.0 – 1.1.1

A look of your own. custom_style (with style: "custom") is the field that actually changes how the video looks; custom_graphics_style styles the text layer Product Showcase draws over the product video, and custom_style_refine: false uses your text verbatim so a campaign keeps one look. facelessad_get_video returns the expanded text as customStyle for exactly that.

SaaS UI Ad takes screenshot_urls — public https URLs of your app's screens. They are decomposed with vision and rebuilt as an animated demo, which is what the tool is for; without them the ad is built from the written description alone. How many fit depends on the length (screenshots.max in facelessad_list_tools): 1 short, 3 medium, 4 long.

Character does dialogue. speakers: 2 makes it a conversation between two characters, and the ad structure has to match — facelessad_list_tools returns speakerStructures.one and .two, and a mismatch is rejected rather than quietly built as a one-voice video. voice_right is the second speaker's voice; omit it and a distinct one is picked automatically.

brand_kit_id picks which brand to use on a multi-brand account instead of always taking the account default (facelessad_list_brand_kits).

1.0.1

Seven tool-specific fields were reachable through the HTTP API but missing from this package's schema, and the MCP SDK strips unknown keys — so an assistant could not use them at all: product_image_urls (extra product angles) and, for Video Banner, texts, text_mode, background_image_url, badge_image_url, badge and photo_query. The schema now mirrors the hosted connector at /mcp field for field.