roasr-mcp
OfficialProvides access to Google Ads analytics via RoASr, including audit findings, KPI summaries, daily metrics, breakdowns, and campaign data.
Provides access to Meta (Facebook) ad analytics via RoASr, including audit findings, KPI summaries, daily metrics, breakdowns, and creative analysis.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@roasr-mcp Show me the KPI summary for last week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.jsRelated MCP server: mcp-meta-marketing
Tools
Tool | Description | Endpoint · scope |
| AI-audit findings by priority (optional client filter) |
|
| Ad KPI summary over a date window (spend, impressions, clicks, conversions, revenue, CTR, CPC, CPM, ROAS, CPA, reach, frequency). Optional |
|
| Daily metric time series over a date window (incl. reach/frequency) — for trends and charts. Optional |
|
| Metric breakdown by dimension ( |
|
| Per-campaign/adset metrics and KPIs over a date window (spend, CTR, CPC, ROAS, CPA, reach, frequency…), sorted by spend |
|
| Conversion breakdown by action type over a date window: |
|
| Workspace clients with context |
|
| Competitor creative tag leaderboard (days_live ≈ winner) |
|
| Search stored competitor creatives (hook / headline / tags / brand) |
|
| Vision breakdown of a creative by |
|
| Rich platform signals by |
|
| 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 |
|
| Direct only. Ads with moderation state and metrics: |
|
| Direct only. Which Yandex.Metrika goals the account's conversions are counted against. No date window — current config. Empty goals ⇒ conversions cannot be attributed |
|
| Direct only. One call for the four Direct kinds by |
|
| Plan limits and the remaining daily Yandex API unit quota (Direct meters per login; its Reports endpoint hides its own consumption) |
|
| The one write tool. Pauses/resumes a live Direct campaign, only within permissions the account owner granted for that key. Idempotent by |
|
| Status and attempt history of a write command — resolves one left in |
|
roasr_metrics_summary/roasr_metrics_daily/roasr_metrics_breakdown/roasr_metrics_campaigns/roasr_metrics_actions/roasr_signalsshare the same date-window params:since/until(YYYY-MM-DD,sincetakes priority) orsinceDays(1–365, default 30), plus optionalaccountId/clientIdfilters.roasr_metrics_breakdownalso requiresdimensionand acceptslimit(1–200, default 50).roasr_metrics_campaignsacceptslevel(campaigndefault, oradset) andlimit(1–200, default 50); its response includesdataSince— the earliest date entity-level data has been collected since.roasr_metrics_summary/roasr_metrics_dailyaccept an optionalentityRef(campaign:<id>|adset:<id>) to scope to one entity instead of the whole workspace.roasr_signalsrequireskindand acceptslimit(1–200, default 50); its response includesasOf(per-account latest).reach/frequency(summary/daily/breakdown) are Meta-only —nullfor older data or non-Meta accounts;reachis a sum of daily reach (not de-duplicated),frequencyis always the derivedimpressions/reach. Action buckets are not additive —engagementis an aggregate ofreactions/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 |
| ✅ | — (server exits with an actionable error if missing) |
| — |
|
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.tsLayout: 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 |
The cross-platform working method: order of analysis, per-platform gotchas, ready workflows, safety rules for the write tool | |
Yandex Direct in depth — goal selection before any conversion number, archived campaigns, | |
Driving RoASr from Hermes (remote HTTP MCP) | |
Driving RoASr from OpenClaw (remote HTTP or local stdio) |
Notes / invariants
stdout is protocol-only — all logs go to
stderr(a strayconsole.logbreaks 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_analyzereturns a stored breakdown.
License
Available Tools
18 toolsroasr_campaign_set_stateA
Pause or resume one advertising campaign (Yandex Direct). This CHANGES the live ad account. It only works if the account owner granted your API key permission for this operation and listed this campaign as allowed; otherwise it returns a permission error naming what to enable. Returns a command with a state: applied (confirmed), verifying/unknown (not confirmed yet — poll roasr_command_get), partial, failed, conflict or rejected. On a timeout or network error, retry with the SAME idempotencyKey: the repeat returns the original command instead of changing the campaign twice.
Inputs: state (required), accountId (required), campaignId (required), idempotencyKey.
roasr_command_getA
Status and attempt history of a write command created by roasr_campaign_set_state: final state, per-target results, the ad platform request id and the API points it consumed. Use it to resolve a command left in verifying or unknown.
Inputs: commandId (required).
roasr_limitsA
Subscription plan, its limits (ad accounts, AI audits, competitors), the API rate tier, and the remaining Yandex Direct daily quota per account. Call this before heavy report pulls: Direct enforces a daily unit budget per login, its report service does not report unit usage at all, and only five reports may be queued at once.
Inputs: no named parameters.
roasr_list_clientsA
Workspace clients with their context (name, niche, margin, status) — for analysis scoped to a specific client.
Inputs: no named parameters.
roasr_list_findingsA
AI audit findings across the connected ad accounts (Meta, Google, Yandex Direct): issues ranked by priority (severity high/med/low) with a stable status. Can be scoped to one client.
Inputs: clientId.
roasr_metrics_actionsA
Workspace conversions broken down by action type for a date window: raw — the plain action-type → value map, buckets — canonical buckets (purchase, lead, add_to_cart, complete_registration, landing_page_view, engagement…). Buckets are NOT additive: engagement is an aggregate and reactions/comments/shares are its components (summing them double-counts).
Inputs: since, until, clientId, accountId, +1 more.
roasr_metrics_breakdownA
Metrics broken down by dimension: audience | placement | platform | country | region | device | dma | hourly. Returns segments with metrics (including reach/frequency — Meta-only, null for older or non-Meta data) as of the latest snapshot date (asOf) inside the window.
Inputs: dimension (required), limit, since, until, +3 more.
roasr_metrics_campaignsA
Per-campaign or per-adset metrics and KPIs for a date window (spend, CTR, CPC, ROAS, CPA, reach, frequency…), sorted by spend. reach/frequency are Meta-only (null for older or non-Meta data). dataSince is the earliest date entity-level data has been collected since: a window earlier than that comes back empty.
Inputs: level, limit, since, until, +3 more.
roasr_metrics_dailyA
Daily metric series for the workspace over a date window (date, spend, impressions, clicks, conversions, revenue, reach, frequency) — for trends and charts. reach/frequency are Meta-only (null for older data and non-Meta accounts); daily reach must not be summed across days. entityRef narrows to a single campaign/adset.
Inputs: since, until, clientId, accountId, +2 more.
roasr_metrics_summaryA
Workspace ad KPIs for a date window: spend, impressions, clicks, conversions, revenue, CTR, CPC, CPM, ROAS, CPA, reach, frequency. reach/frequency are Meta-only (null for older data and non-Meta accounts); frequency = impressions/reach and is not additive across days. entityRef narrows to a single campaign/adset.
Inputs: since, until, clientId, accountId, +2 more.
roasr_signalsA
Rich signals for a date window by kind: Google search terms, keyword quality score, impression share, auction insights, conversion actions by category, asset performance, landing pages, shopping, video funnel, bidding, asset groups; Meta — ad quality rankings. Per-account latest snapshot inside the window (payloads of different accounts are not aggregated); the response is capped by limit (default 50) — this is intel the plain metrics tools do not have.
Inputs: kind (required), limit, since, until, +3 more.
roasr_spy_searchA
Search stored competitor creatives from the Meta Ad Library: by keyword (query — hook/headline/tags) and/or by brand (brand — exact page-name filter). Empty input returns the top by days_live. Returns hook, headline, format, tags, country and ad_archive_id for a follow-up Vision analysis. days_live is a proxy for what wins.
Inputs: brand, limit, query.
roasr_spy_tag_leaderboardA
Leaderboard of competitor creative tags from the Meta Ad Library: which formats/angles/offers are used most and live longest (days_live is a proxy for what wins). This is intel the plain metrics tools do not have.
Inputs: limit.
roasr_vision_analyzeA
Vision analysis of one competitor creative by ad_archive_id: hook, angle, format, strengths and risks, plus a video transcript when available. Analysis the plain metrics tools do not have. Find the creative with roasr_spy_search first; if it has not been analysed yet, start the analysis inside the app.
Inputs: adArchiveId (required).
roasr_yandex_adsA
Yandex Direct only, read-only. Ads with moderation status and metrics for a date window: state/status/statusClarification, whether the ad has a second headline, sitelinks, UTM markup, an image, a turbo page, plus impressions/clicks/spend/conversions/ctr. Use it to find rejected ads, or ads missing a second headline or link markup. Errors if accountId points to a non-Yandex account.
Inputs: since, until, clientId, accountId, +1 more.
roasr_yandex_breakdownA
Yandex Direct only, read-only. One of the Direct-specific breakdowns collected as signals: search_queries (search terms with spend/conversions — same data as roasr_yandex_search_queries), keywords (keyword-level state, bids, impressions/clicks by search vs network), ads (ad status and metrics — same data as roasr_yandex_ads), bidding (per-campaign daily budget and bid strategy). Errors if accountId points to a non-Yandex account. For campaign/adset totals or device/region/audience/placement splits on a Yandex account, use roasr_metrics_campaigns / roasr_metrics_breakdown instead — those already work for any platform.
Inputs: dimension (required), since, until, clientId, +2 more.
roasr_yandex_goalsA
Yandex Direct only, read-only. Which Yandex.Metrika goals are selected for an account, and hence which goals its conversions are counted against — no window, this is current config, not a metric series. Empty goals means that account's conversions cannot be attributed to a goal; do not treat its conversion numbers as trustworthy. Errors if accountId points to a non-Yandex account.
Inputs: clientId, accountId.
roasr_yandex_search_queriesA
Yandex Direct only, read-only. Search queries for a date window: query text, campaign/ad group, match type, impressions, clicks, spend, conversions. The most valuable Direct signal — use it to find what share of spend went to queries with zero conversions. Errors if accountId points to a non-Yandex account.
Inputs: since, until, clientId, accountId, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Most tools have clearly distinct purposes: metrics tools are separated by granularity (summary, daily, breakdown, campaigns, actions), and spy/vision tools are differentiated. The only overlap is roasr_yandex_breakdown duplicating data from roasr_yandex_search_queries and roasr_yandex_ads, but the descriptions explicitly clarify when to use which, minimizing misselection.
All tools share the roasr_ prefix and follow snake_case naming. The pattern is not strictly verb_noun (e.g., roasr_metrics_summary is a noun phrase), but it is consistent across domains: roasr_metrics_*, roasr_spy_*, roasr_yandex_*, roasr_campaign_set_state, and roasr_command_get follow a predictable structure.
18 tools is slightly above the typical 15 but appropriate for the server's broad scope: ad analytics, competitor intelligence, vision analysis, Yandex account management, and subscription limits. Each tool serves a distinct purpose and the count is not overwhelming for the feature set.
The tool surface covers core read-only analytics (metrics, findings, signals), competitor research (spy search, vision), and a limited write capability (pause/resume campaigns) with proper command status tracking. Minor gaps exist, such as no campaign creation or update tools, but the server appears focused on analysis and optimization rather than full campaign management, so the coverage is largely complete.
Maintenance
Related MCP Connectors
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Reddit Ads MCP server: run Reddit campaigns, ad groups, ads and reports from AI.
Related MCP Servers
- AlicenseAqualityCmaintenanceCross-platform ad management MCP server for Google Ads and Meta Ads. Campaign analytics, A/B testing with z-test, anomaly detection, and budget reallocation. 15 tools, 60 tests.1787 npmMIT
- AlicenseAqualityDmaintenanceMCP server that wraps the Meta Marketing API (Graph API v25.0) as semantic tools for LLM agents.181MIT
- AlicenseNot gradedqualityAmaintenanceMCP server for VK Ads API (myTarget v2) that allows AI agents to manage advertising accounts: create and modify campaigns, ads, upload creatives, and fetch statistics.145 npm6Apache 2.0

Markifact MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceA universal marketing MCP server that lets AI clients manage 20+ ad and marketing platforms (Google Ads, Meta, TikTok, etc.) with 500+ operations, including write actions with user approval.59MIT