roasr-mcp

<!-- mcp-name: io.github.RoASr-com/roasr-mcp -->

English · Русский

MCP server for RoASr — connect Claude, ChatGPT, Codex, Cursor, or any MCP-compatible client to your RoASr ad-analytics workspace: Meta, Google Ads and Yandex Direct ad-audit findings, KPI summaries, competitor spy and Vision creative analysis. A thin, dependency-free client over the public /v1 REST API.

Auth is by your pg_live_… API key; workspace isolation and scopes are enforced API-side. The server is stateless, and read-only apart from one Yandex Direct campaign pause/resume tool that works solely inside permissions you granted.

---

Quick start

1. Get an API key

Sign in at https://roasr.com → Settings → API keys → create a pg_live_… key with the scopes you need (shown once).

2. Connect — pick one

A. Remote connector — no install (Claude.ai web, ChatGPT, Codex, or any HTTP/streamable-http MCP client):

URL:  https://roasr.com/api/mcp
Auth: Bearer pg_live_…

The tool catalog at that URL is public (any client can list the tools without a key); every actual tool call requires the Authorization: Bearer pg_live_… header — the API key scopes the call to your workspace. Most MCP-capable clients (Claude.ai, ChatGPT connectors, Codex) accept this URL + bearer token directly in their "add remote MCP server" UI, no local process needed.

B. Local via npx (Claude Desktop, Cursor, Claude Code) — add to your MCP config:

{
  "mcpServers": {
    "roasr": {
      "command": "npx",
      "args": ["-y", "roasr-mcp"],
      "env": {
        "ROASR_API_KEY": "pg_live_…",
        "ROASR_BASE_URL": "https://roasr.com"
      }
    }
  }
}

Until the npm package is published, use "args": ["-y", "github:RoASr-com/roasr-mcp"].

C. From source:

git clone https://github.com/RoASr-com/roasr-mcp && cd roasr-mcp
npm install && npm run build
ROASR_API_KEY=pg_live_… node dist/index.js

---

Tools

Tool	Description	Endpoint · scope
roasr_list_findings	AI-audit findings by priority (optional client filter)	GET /v1/findings · findings:read
roasr_metrics_summary	Ad KPI summary over a date window (spend, impressions, clicks, conversions, revenue, CTR, CPC, CPM, ROAS, CPA, reach, frequency). Optional entityRef scopes to one campaign/adset	GET /v1/metrics/summary · metrics:read
roasr_metrics_daily	Daily metric time series over a date window (incl. reach/frequency) — for trends and charts. Optional entityRef scopes to one campaign/adset	GET /v1/metrics/daily · metrics:read
roasr_metrics_breakdown	Metric breakdown by dimension (audience / placement / platform / country / region / device / dma / hourly), segments as of the latest snapshot date in the window	GET /v1/metrics/breakdowns · metrics:read
roasr_metrics_campaigns	Per-campaign/adset metrics and KPIs over a date window (spend, CTR, CPC, ROAS, CPA, reach, frequency…), sorted by spend	GET /v1/metrics/campaigns · metrics:read
roasr_metrics_actions	Conversion breakdown by action type over a date window: actions (raw action-type → sum map) + buckets (canonical: purchase, lead, add_to_cart, complete_registration, landing_page_view, engagement…)	GET /v1/metrics/actions · metrics:read
roasr_list_clients	Workspace clients with context	GET /v1/clients · clients:read
roasr_spy_tag_leaderboard	Competitor creative tag leaderboard (days_live ≈ winner)	GET /v1/spy/tags · spy:read
roasr_spy_search	Search stored competitor creatives (hook / headline / tags / brand)	GET /v1/spy/search · spy:read
roasr_vision_analyze	Vision breakdown of a creative by ad_archive_id (hook / angle / risks + transcript)	GET /v1/vision/analyze · spy:read
roasr_signals	Rich platform signals by kind (required — one of 16 SIGNAL_KINDS: search terms, keyword quality score, impression share, auction insights, conversion actions, asset performance, landing pages, shopping, video funnel, bidding, asset groups, Meta ad quality + the four Yandex Direct kinds). Per-account latest snapshot in the window, response capped by limit	GET /v1/signals · metrics:read
roasr_yandex_search_queries	Direct only. Search queries for a window: text, campaign/ad group, match type, impressions, clicks, spend, conversions. The strongest Direct signal — sizes the share of spend on queries with zero conversions	GET /v1/signals · metrics:read
roasr_yandex_ads	Direct only. Ads with moderation state and metrics: state/status/statusClarification, second headline, sitelinks, UTM markup, image, turbo page	GET /v1/signals · metrics:read
roasr_yandex_goals	Direct only. Which Yandex.Metrika goals the account's conversions are counted against. No date window — current config. Empty goals ⇒ conversions cannot be attributed	GET /v1/yandex/goals · metrics:read
roasr_yandex_breakdown	Direct only. One call for the four Direct kinds by dimension: search_queries | keywords | ads | bidding	GET /v1/signals · metrics:read
roasr_limits	Plan limits and the remaining daily Yandex API unit quota (Direct meters per login; its Reports endpoint hides its own consumption)	GET /v1/limits · metrics:read
roasr_campaign_set_state	The one write tool. Pauses/resumes a live Direct campaign, only within permissions the account owner granted for that key. Idempotent by idempotencyKey	POST /v1/campaigns/state · campaigns:write
roasr_command_get	Status and attempt history of a write command — resolves one left in verifying/unknown	GET /v1/commands/{id} · campaigns:read

roasr_metrics_summary / roasr_metrics_daily / roasr_metrics_breakdown / roasr_metrics_campaigns / roasr_metrics_actions / roasr_signals share the same date-window params: since/until (YYYY-MM-DD, since takes priority) or sinceDays (1–365, default 30), plus optional accountId/clientId filters. roasr_metrics_breakdown also requires dimension and accepts limit (1–200, default 50). roasr_metrics_campaigns accepts level (campaign default, or adset) and limit (1–200, default 50); its response includes dataSince — the earliest date entity-level data has been collected since. roasr_metrics_summary/roasr_metrics_daily accept an optional entityRef (campaign:<id> | adset:<id>) to scope to one entity instead of the whole workspace. roasr_signals requires kind and accepts limit (1–200, default 50); its response includes asOf (per-account latest). reach/frequency (summary/daily/breakdown) are Meta-only — null for older data or non-Meta accounts; reach is a sum of daily reach (not de-duplicated), frequency is always the derived impressions/reach. Action buckets are not additive — engagement is an aggregate of reactions/comments/shares, don't sum them together.

Spy (spy_search + vision_analyze) is the edge — your AI gets data that lives nowhere else. Ad Library scans and Vision analysis (LLM/credits) run inside the RoASr app; this server returns the already-stored result.

---

Configuration

Env	Required	Default
ROASR_API_KEY	✅	— (server exits with an actionable error if missing)
ROASR_BASE_URL	—	https://roasr.com

---

Development

npm install      # installs devDeps + builds dist/ (prepare hook)
npm run build    # tsc → dist/index.js (executable bin, shebang)
npm run dev      # tsx src/index.ts

Layout: src/index.ts (entry, env validation, fail-loud) · src/protocol.ts (dependency-free JSON-RPC 2.0 stdio + runMcpServer/ToolDef) · src/client.ts (RoasrClient, Bearer auth, error-envelope unwrap) · src/tools.ts (buildTools → 18 tools).

Unit tests (vitest, fake client, no network) live in the RoASr monorepo, which is the source of truth for src/ — this repository is its published mirror.

---

Agent skills

Tool schemas tell an agent what it can call; these tell it how to reason. Drop the folder into your agent's skills directory (Claude Code: .claude/skills/), or just paste the file into context.

Skill	For
SKILL.md	The cross-platform working method: order of analysis, per-platform gotchas, ready workflows, safety rules for the write tool
skills/yandex-direct	Yandex Direct in depth — goal selection before any conversion number, archived campaigns, State vs Status, micro-units, the daily unit quota
skills/hermes	Driving RoASr from Hermes (remote HTTP MCP)
skills/openclaw	Driving RoASr from OpenClaw (remote HTTP or local stdio)

---

Notes / invariants

• stdout is protocol-only — all logs go to stderr (a stray console.log breaks JSON-RPC).
• Fail-loud — missing ROASR_API_KEY → actionable stderr message + exit(1).
• Tool errors surface as { isError: true } (MCP convention), so the client can recover.
• Read-only except roasr_campaign_set_state — that one pauses/resumes a live Yandex Direct campaign, and only inside the permissions the account owner granted for that key. Scopes are enforced API-side.
• Vision / Ad-Library results are pre-computed in the app — vision_analyze returns a stored breakdown.

---

License

MIT © 2026 SmartFlow LLC — roasr.com