RivlWatch MCP server

Bring your RivlWatch competitor intelligence into any MCP client (Claude Desktop, Claude Code, OpenClaw, etc.). Ask in plain language — "which of my rivals sold the most today?", "what is allbirds running on Meta right now?", "summarize the hooks in my Q4 Winners collection" — and it answers from your live RivlWatch account.

Full public docs: https://rivlwatch.com/mcp

Tools

| Tool | What it does | Cost | |------|--------------|------| | whoami | Confirm the connection + show the signed-in account/plan | free | | list_my_stores | Your tracked stores with today's revenue, orders, products | free | | store_creatives | One tracked store's full Meta ads library: copy, days running, reach, media | free | | saved_ads | Your saved-ads swipe file + Collections + labels + cached AI reads | free | | saved_tiktok_finds | Your saved TikTok Shop products + monitored TikTok videos | free | | my_top_ads | Reach-ranked top creatives across your tracked stores (or the global pool) | free | | ad_audience | One ad's EU demographics: gender split, age bands, top countries | free | | winning_creatives | The global winning-creatives discovery feed (filter by window/format/country/AI) | free | | track_store | Start tracking a store by URL (Shopify, Cloudflare-Shopify, or ads-only) | uses a plan store slot |

All calls inherit your subscription server-side — the MCP can never do more than your account can, a lapsed plan returns a clear error, and all key traffic shares one per-account rate budget (HTTP 429 + Retry-After when exceeded). track_store is the only tool with a side effect; everything else is read-only.

Setup

1. Get an API key: RivlWatch → Settings → API keys → Create API key. Copy the rivl_… token (shown once).

2. Install deps (once):

   cd mcp-server
   npm install

3. Register it with your MCP client.

   Claude Desktop — edit claude_desktop_config.json (Settings → Developer → Edit Config):

   {
     "mcpServers": {
       "rivlwatch": {
         "command": "node",
         "args": ["/ABSOLUTE/PATH/TO/mcp-server/index.js"],
         "env": { "RIVLWATCH_API_KEY": "rivl_your_key_here" }
       }
     }
   }

   Restart Claude Desktop. You'll see the rivlwatch tools available.

   Claude Code — claude mcp add rivlwatch -e RIVLWATCH_API_KEY=rivl_… -- node /ABS/PATH/mcp-server/index.js

Verify

RIVLWATCH_API_KEY=rivl_… npm run smoke

Lists the tools and calls each read tool against the live API. Point at a local dev server with RIVLWATCH_API_BASE=http://localhost:3007.

Media URLs

Tool responses link ad creatives two ways: archived media under https://rivlwatch.com/api/media/... is durable — the endpoint requires your API key (Authorization: Bearer rivl_…) or a logged-in browser, and resolves to an unguessable storage URL; live fbcdn.net URLs are public but expire after ~4 days.

Config

| Env | Default | Notes | |-----|---------|-------| | RIVLWATCH_API_KEY | — | required — your rivl_… key | | RIVLWATCH_API_BASE | https://rivlwatch.com | override for local/staging |

Pairs with the RivlWatch skill

Drop rivlwatch-skill/ into your agent's skills folder (e.g. ~/.claude/skills/rivlwatch/ for Claude Code, or your OpenClaw skills dir) so the model knows the best workflows for these tools — see rivlwatch-skill/SKILL.md.