pubweb-ads-mcp

An MCP server that gives Claude a knowledge base of your scraped competitor ads — semantic search, ad copy, images/videos, and the landing→destination funnels — so Claude can reason over them like a RAG.

It's a thin, secure wrapper over the pubweb external API (/api/v1): one bearer API key, every call scoped server-side to your account, read-only.

Setup (2 steps)

1. Create an API key — in pubweb → Settings → API Keys → "Create key for Claude/MCP". Pick the abilities v1:ads:read and v1:ads:search. Copy the key (shown once).

2. Add the server to your MCP client.

Claude Desktop (claude_desktop_config.json) or Claude Code (.mcp.json):

{
  "mcpServers": {
    "pubweb-ads": {
      "command": "npx",
      "args": ["-y", "pubweb-ads-mcp"],
      "env": { "PUBWEB_API_KEY": "PASTE_YOUR_KEY_HERE" }
    }
  }
}

That's it — restart the client and ask Claude things like "search the ad knowledge base for job-offer ads" or "show me the funnel of ad <id>".

Self-hosted / staging? add "PUBWEB_API_URL": "https://your-domain" to env (default https://app.pubweb.ai).

Run without npx (local checkout)

cd mcp/ads-mcp && npm install
PUBWEB_API_KEY=... node src/index.js          # stdio server
PUBWEB_API_KEY=... npm run smoke               # lists the tools (sanity check)

…and point the MCP client's command/args at node /abs/path/mcp/ads-mcp/src/index.js.

Tools

| Tool | What it does | |------|--------------| | ads_search(query, network?, funnel_type?) | Semantic (vector) search — multilingual; ranked ads with copy + thumbnail + funnel summary | | ads_browse(q?, network?, funnel_type?, format?, from?, to?, per_page?) | Keyword/filter browse, paginated | | ad_get(id) | One ad — full copy, media list, funnel summary | | ad_media(id) | Presigned image/video URLs (30-min TTL) | | ad_funnel(id) | The ad's landing→destination funnel | | targets_list() | Competitor domains you track, with ad counts | | adx_kpis(site?, from?, to?) | AdX ad-serving funnel KPIs for your sites (requests/fills/viewability/ctr) — needs v1:adx:read | | adx_timeseries(site?, from?, to?, granularity?) | AdX funnel over time (hour/day/week) | | adx_fill_report(site?, from?, to?) | AdX funnel by block / country / price bucket / size / device | | whoami() | Verify the key + see its abilities (setup/debug) |

Security

• Bearer key only — never your password/session. The key is v1:ads:read[/search] scoped; it can't touch anything else. Stored only in your local MCP config.
• The server never sees more than your own ads (scoped server-side by the key owner).
• Read-only: no tool can create, modify, or delete anything.
• Rate-limited per key (HTTP 429 + Retry-After surfaces as a normal tool error).

Releasing (maintainers)

Publishing is automated by .github/workflows/publish-mcp.yml — it fires only on changes under mcp/ads-mcp/** and publishes to npm only when version here is bumped (an unbumped change runs but skips publish). So a release is just:

npm version patch    # or minor / major — bumps package.json
git commit -am "release(ads-mcp): vX.Y.Z" && git push   # → workflow publishes

The package is unscoped — it publishes to the personal npm account that owns the token. One-time setup by the repo owner: create an automation token on npmjs.com, then add it as the GitHub repo secret NPM_TOKEN.