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

Related MCP server: google-ads-transparency-mcp

Tools

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

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.

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