# AutoWhisper MCP

A marketing department for any MCP client (Claude Desktop, Cursor, Windsurf, n8n, …) — turn your product into **batches of ready-to-run ad creatives** (UGC video, posts, images), get advice on **which creative to fund**, and keep **every channel alive across 30+ platforms**, all in natural language.

It's the same CMO as the AutoWhisper dashboard, exposed over MCP. Honest scope: posting ≠ traffic — reach comes from your paid campaigns; this makes sure the creatives convert and your storefront doesn't kill them.

## Connect by URL (recommended)

No install. Point your client at the remote server:

```
https://autowhisper.xyz/mcp
```

- **Claude.ai / Claude Desktop** — Settings → Connectors → Add custom connector, paste the URL, then click **Approve** on the page that opens (OAuth). ChatGPT and other apps: add a connector the same way.
- **Claude Code** — run `claude mcp add --transport http autowhisper https://autowhisper.xyz/mcp`, then type `/mcp` in Claude Code and choose autowhisper → **Authenticate**.
- **Cursor / VS Code / other HTTP-capable clients** — add the same URL; they'll open the same Approve page. Already have an AutoWhisper API token? You can send it as `Authorization: Bearer <token>` instead.

Same tools and replies as the npm package below, always up to date (no version to upgrade).

## Install via npm (local stdio clients only)

Use this only if your client can't connect to a URL. Add to your MCP client config:

```json
{
  "mcpServers": {
    "autowhisper": {
      "command": "npx",
      "args": ["-y", "autowhisper-mcp"],
      "env": { "AUTOWHISPER_API_TOKEN": "your_token_here" }
    }
  }
}
```

Get your token at **[autowhisper.xyz/skill](https://autowhisper.xyz/skill)** → **Settings → Connect your agent → Generate token**. New accounts get free credits.

## Tools

- **`autowhisper_context`** — read product facts, material aliases and available presets in an explicit workspace.
- **`autowhisper_create_content`** — submit an explicit preset content batch directly. Returns `accepted` immediately, then uses native confirmation and generation credits. Reuse the same `request_id` and identical payload on retries.
- **`autowhisper_update_task`** — revise, resume or render explicit items using the current task/item revisions and server-returned preview approval.
- **`autowhisper_task`** — read exactly one `request_id` or `task_id`. `applied` means the command reached the native task; only `delivery_complete=true` means the requested deliverable is ready.

Task reads include actual native `billing` (charges, refunds, remaining quote,
wallet versus included usage). Reused charge identities count once. Partial
carousel artifacts contain the current delivered cards and a version-bound render
action; `previous_previews` is historical content.

These four tools require `workspace_id`. Discover workspace IDs with `autowhisper_status`, then read context before creating. Follow the returned `next_actions` for confirmation and review. Unknown submission? Query the original request ID before retrying; do not invent a new ID or fall back to a separately charged CMO turn. `requires_planning` means explain the unsupported requirement and offer CMO advice. Production availability depends on the backend rollout flag and user allowlist; this change is not yet published.

- **`autowhisper_cmo`** — ask for marketing judgment or planning, such as *"Which creative should I run first?"*. Prefer the direct content tools when the requested product, content and changes are explicit.
- **`autowhisper_products_summary`** — fast product counts by account/workspace. Use for *"how many products do I have?"* instead of spending a CMO chat turn.
- **`autowhisper_products`** — fast product list, with optional workspace/archive filters.
- **`autowhisper_status`** — fast CMO/account snapshot: products, feed, platforms, wallet, and automation settings.
- **`autowhisper_feed`** — fast CMO feed list with status counts and available approve/reject/dismiss actions.
- **`autowhisper_posts`** — fast post queue list, optionally filtered by status.
- **`autowhisper_wallet`** — fast credit balance.
- **`autowhisper_platforms`** — fast connected-platform list and connection health.
- **`autowhisper_performance`** — cross-channel results for one workspace: four-layer funnel, per-channel breakdown, ad spend over the window. The only read that answers *did any of this work?* rather than *what did we make?* — reach for it before advising which creative to fund or scale. `ad_spend_cents` is `null`, not `0`, when there is no active workspace to read: `null` means we cannot answer, `0` would assert nothing was spent.
- **`autowhisper_action`** — direct approve/reject/dismiss/publish/reschedule/retry/boost actions. High-impact actions return a confirmation id. **Approving publishes**: it schedules the piece to every connected platform, and a video draft also starts rendering and charges for it. With nothing connected it goes nowhere, and connecting later does not go back for it — the result says which happened.
- **`autowhisper_edit_content`** — direct title/body/hook/CTA/tone/keyword edits without a generation run.
- **`autowhisper_confirm`** — approve or decline any high-impact action the CMO or direct-action tool asks about.

> **Adding a product:** lead with a product **URL** (*"add my product https://mystore.com/widget"*) — the CMO extracts the image from the page. A text-only description won't create it (placeholder/stock images are rejected).

> **Asking for an ad plan:** `autowhisper_cmo` also plans campaigns — *"Give me a concrete ad-targeting plan for my product, starting markets, targeting, and what to avoid."* The plan arrives as a card (markets, age, interest seeds, objective, which creative to run). It's prose for a human, in the owner's UI language — **translate it before feeding it to an ad API**. It **suggests** a starting platform, it doesn't lock one. It leaves out the **budget** (ask the owner) and gives interest **search terms rather than platform IDs** (resolve them in your ad tool). Grounded advice runs a live web search and can take **over two minutes** — if the tool times out, don't resend; that starts a second, separately charged turn instead of resuming the first. AutoWhisper plans and supplies creative; your ads MCP executes — never report that AutoWhisper "ran the campaign." No ads MCP connected yet? Don't name or install a third-party npm package for this — point the user at Meta's own developer docs instead: [Meta's Ads MCP documentation](https://developers.facebook.com/documentation/ads-commerce/ads-ai-connectors/ads-mcp-server/ads-mcp-server-overview).

## One-time setup

To publish, ask the CMO to connect a social account — OAuth platforms return a link you click once. After that, publishing is hands-off.

## Config

| Env var | Default | |
|---|---|---|
| `AUTOWHISPER_API_TOKEN` | — | **required** — your API token |
| `AUTOWHISPER_BASE_URL` | `https://autowhisper.xyz` | override for self-host/staging |

## License

Offline contract checks: `AUTOWHISPER_CONTRACT_FILE=test/fixtures/agent_content_contract.json npm test`. The fixture is exported by the Rails contract test (`UPDATE_AGENT_CONTENT_CONTRACT=1`); regenerate `src/content-contract.ts` from that exact JSON when updating. Live contract checks remain a separate release verification.

MIT