{
  "markdown": "# AdOps MCP\n\n**CSV-first analytics & optimization for Google Ads + Meta Ads — inside Claude, Cursor, and any MCP client.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://www.typescriptlang.org/)\n[![MCP](https://img.shields.io/badge/MCP-1.29-2A9D8F.svg)](https://modelcontextprotocol.io/)\n\nExport a CSV from Google Ads or Meta Ads Manager → import into AdOps → ask your AI assistant anything about your campaigns.\n\nNo OAuth. No developer tokens. No API approval queues. Your data stays on your machine.\n\n---\n\n## Why CSV-first?\n\nGoogle Ads API and Meta Marketing API are powerful but gated: developer token approval takes days, Meta app review takes weeks, OAuth flows are fragile. For most advertisers those barriers never clear.\n\nAdOps takes a different path. Every ad platform's dashboard already has a **Download** / **Export** button that produces a CSV of exactly what you care about: campaign performance, day-segmented metrics, spend, conversions, ROAS. AdOps reads that CSV and runs the same analysis you'd get from a $200/mo optimization suite — anomaly detection, budget allocation, A/B significance, forecasting, industry benchmarks — directly inside your AI assistant.\n\nYou stay in control of your data. You don't hand credentials to a third party. You don't wait 3 weeks for a review.\n\n---\n\n## Features\n\n- **17 MCP tools** covering the full ad analytics lifecycle\n- **4 MCP resources** for at-a-glance dashboards\n- **CSV import** from Google Ads Editor, Google Ads web UI, and Meta Ads Manager — with automatic format detection (US vs European number formatting, CRLF vs LF, BOM handling)\n- **Unified cross-platform schema** — Google and Meta campaigns normalized into a single `UnifiedCampaign` / `UnifiedMetrics` model\n- **AI-powered recommendations** — budget reallocation, scaling high-ROAS campaigns, pausing zero-conversion ones\n- **Bulk-edit CSV export** — turn recommendations into Google Ads Editor / Meta Ads Manager CSVs you can paste straight into the dashboard for one-click bulk updates\n- **Statistical anomaly detection** — CPC spikes, CTR drops, spend surges, sensitivity-configurable\n- **A/B test analysis** with confidence scoring\n- **9-vertical industry benchmarks** built-in (eCommerce, SaaS, B2B, etc.)\n- **Spend & conversion forecasting** (7/14/30 days)\n- **Demo mode** — seed a realistic portfolio to try the tools before importing your own data\n- **91 automated tests** — TypeScript strict mode, Zod validation throughout\n\n---\n\n## Quick Start\n\n```bash\nnpm i adops-mcp-server\n```\n\nAdd to your MCP client (Claude Desktop `claude_desktop_config.json`, Cursor, VS Code, Windsurf):\n\n```json\n{\n  \"mcpServers\": {\n    \"adops\": {\n      \"command\": \"node\",\n      \"args\": [\"path/to/node_modules/adops-mcp-server/dist/index.js\"]\n    }\n  }\n}\n```\n\nRestart your client. Then, inside Claude:\n\n```\n> Seed demo data so I can explore AdOps\n```\n(calls `ad_demo_seed`)\n\nOr import your real data:\n\n```\n> Import ~/Downloads/google-ads-report.csv as a Google Ads CSV\n```\n(calls `ad_csv_import` with platform=google, csv_path=...)\n\n---\n\n## Exporting CSV from Your Ad Dashboard\n\n### Google Ads\n\n1. Open [ads.google.com](https://ads.google.com) → **Campaigns** view\n2. (Optional) Click **Segment → Day** in the toolbar for daily metrics\n3. Click **Download** (⬇) icon → choose **.csv** format\n4. Save to disk, give the absolute path to `ad_csv_import`\n\n### Meta Ads Manager\n\n1. Open [business.facebook.com](https://business.facebook.com) → **Ads Manager**\n2. Switch to **Campaigns** tab (not Ad Sets or Ads — campaign-level rollups)\n3. (Optional) **Breakdown → Time → Day** for daily metrics\n4. Click **Reports → Export → Campaign performance (.csv)**\n5. Save to disk, give the absolute path to `ad_csv_import`\n\nBoth exports work out-of-the-box with or without day segmentation. Without a Day column, you get one aggregated metric row per campaign. With Day segmentation, you get daily time-series data — which powers forecasting and anomaly detection properly.\n\n---\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `ad_demo_seed` | Seed a realistic cross-platform demo portfolio (8 campaigns, 30 days of metrics) to try AdOps before importing real data |\n| `ad_csv_import` | **Import a Google Ads or Meta Ads CSV export** — every other tool operates on this data |\n| `ads_export_recommendations` | **Export budget_analyze recommendations** as Google Ads Editor CSV, Meta Ads Manager CSV, JSON, or Markdown — one bulk-paste and your ad dashboard reflects the AI's plan |\n| `platform_connect` | Register a data source connection manually (alternative to CSV import, for scripted workflows) |\n| `campaign_list` | List and filter campaigns across all imported platforms |\n| `campaign_create` | Add a campaign manually (useful for what-if planning) |\n| `campaign_update` | Update campaign settings in local storage (budget, status, bidding, schedule) |\n| `campaign_pause_resume` | Batch pause or resume up to 50 campaigns |\n| `ads_report` | Generate unified cross-platform performance report |\n| `budget_analyze` | Analyze budget allocation, produce scaling/pausing recommendations |\n| `budget_reallocate` | Transfer budget between campaigns across platforms |\n| `audience_insights` | Demographic / geographic / device breakdowns |\n| `creative_specs` | Platform-specific image, video, and text requirements reference |\n| `anomaly_detect` | Detect performance anomalies with configurable sensitivity |\n| `ab_test_analyze` | Compare two campaigns with statistical significance testing |\n| `competitor_benchmark` | Compare your metrics against industry averages (9 verticals) |\n| `forecast_spend` | Forecast spend, conversions, ROAS for the next 7/14/30 days |\n\n---\n\n## Resources\n\n| Resource | Description |\n|----------|-------------|\n| `ads://overview` | Cross-platform dashboard summary |\n| `ads://campaigns` | All active campaigns with key metrics |\n| `ads://budget` | Budget allocation across platforms |\n| `ads://alerts` | Recent performance anomalies and warnings |\n\n---\n\n## Unified Metrics Schema\n\nAdOps normalizes metrics across platforms:\n\n| Metric | Formula | Notes |\n|--------|---------|-------|\n| CTR | clicks / impressions × 100 | Click-through rate (%) |\n| CPC | spend / clicks | Cost per click |\n| CPM | spend / impressions × 1000 | Cost per 1000 impressions |\n| ROAS | conversion_value / spend | Return on ad spend |\n| CPA | spend / conversions | Cost per acquisition |\n| Conversion Rate | conversions / clicks × 100 | % |\n\n**CSV column mapping:**\n\n| AdOps Field | Google Ads CSV | Meta Ads CSV |\n|-------------|---------------|--------------|\n| `spend` | `Cost` (USD equivalent auto-converted if micros) | `Amount spent (USD/EUR/...)` |\n| `impressions` | `Impressions` | `Impressions` |\n| `clicks` | `Clicks` | `Link clicks` |\n| `conversions` | `Conversions` | `Results` (Purchases/Leads/etc.) |\n| `conversion_value` | `Conv. value` | `Purchases conversion value` |\n| `reach` | — | `Reach` (Meta-only) |\n| `quality_score` | `Quality Score` (if present) | — (Google-only) |\n\nEuropean locale numbers (`125,50` = 125.50) and semicolon-delimited CSVs are auto-detected.\n\n---\n\n## Configuration\n\nAdOps is stateless from the network's point of view — no API keys, no OAuth. The only configuration is where it persists imported data:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `ADOPS_DATA_DIR` | Directory for JSON persistence | `./data` |\n\nAll other behavior is controlled via tool arguments.\n\n---\n\n## Pricing\n\n| Tier | Price | Features |\n|------|-------|----------|\n| Free | $0 | 1 imported CSV per day, demo mode, all 17 tools read-only |\n| Pro | €24 lifetime | Unlimited imports, full CRUD, all analytics tools |\n| Agency | $59/mo | Multi-account, white-label reports, priority support |\n\nAvailable via [GitHub](https://github.com/enzoemir1/adops-mcp) (self-hosted, free) or the MCPize marketplace (managed).\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/enzoemir1/adops-mcp.git\ncd adops-mcp\nnpm ci\nnpm run build\nnpm test           # 91 tests across 10 suites\nnpm run inspect    # Open MCP Inspector\n```\n\n### Tests\n\n91 tests covering:\n\n- **CSV parser** (11 tests): RFC 4180 quoting, BOM, European/US number formats, delimiter detection\n- **Google Ads CSV import** (7 tests): campaigns report, day segmentation, objective mapping, European locale\n- **Meta Ads CSV import** (5 tests): Meta-specific columns, currency detection from header, objective mapping, reach/frequency capture\n- **Export recommendations** (8 tests): Google Ads Editor CSV format, Meta Ads Manager CSV format, JSON wrapper, Markdown rendering, min_delta_pct filter, limit, by_type summary\n- **Storage**: Connection CRUD, campaign search, metrics aggregation, batch inserts\n- **Analytics**: Metric calculations, performance reports, forecasting, benchmarks\n- **Optimizer**: Budget analysis, reallocation, scaling/pausing recommendations\n- **Anomaly**: CPC spike detection, conversion drops, sensitivity, severity sorting\n- **E2E Workflow**: 14 real user scenarios\n\n---\n\n## Roadmap\n\n- **v1.3** — Add Google Ads Editor `.csv.gz` and Excel `.xlsx` support\n- **v1.4** — Live Google Ads / Meta Ads API integration as an optional enterprise feature (BYOK — bring your own developer token + app review)\n- **v2.0** — Multi-user server mode with JWT auth for team deployments\n\n---\n\n## Pro License\n\nAdOps ships in **Free mode** — `ad_demo_seed`, `ad_csv_import`, `platform_connect`, `campaign_list`, `campaign_create`, `campaign_update`, `campaign_pause_resume`, `ads_report`, `budget_reallocate`, `audience_insights`, and `creative_specs` are open. The following tools require a **Pro license**:\n\n- `ads_export_recommendations` — bulk-edit CSV export for Google Ads Editor / Meta Ads Manager\n- `budget_analyze` — AI budget allocation analysis with action recommendations\n- `anomaly_detect` — statistical anomaly detection\n- `ab_test_analyze` — A/B test z-test with significance + uplift\n- `forecast_spend` — 7/14/30-day spend & ROAS forecast\n- `competitor_benchmark` — industry benchmark comparison\n\n**Buy a Pro License (€24, lifetime, 3 machines):** https://automatiabcn.lemonsqueezy.com/buy/1525c929-832c-4472-a88a-58edbfa4e87b\n\nOr get the **[Indie MCP Stack Bundle](https://automatiabcn.lemonsqueezy.com/buy/55e932fd-8319-47f0-8e95-0b86a29f2617)** (€69, all 4 servers).\n\n```bash\nexport LEMONSQUEEZY_LICENSE_KEY=YOUR-KEY-HERE\n```\n\nOr in your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"adops-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"adops-mcp-server\"],\n      \"env\": { \"LEMONSQUEEZY_LICENSE_KEY\": \"YOUR-KEY-HERE\" }\n    }\n  }\n}\n```\n\nValidation is cached locally for 24 h — fully offline-capable after first run.\n\n---\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\nBuilt by [Automatia BCN](https://github.com/enzoemir1).\n",
  "bytes": 10901,
  "sha": "7b57b26707a4ec76d0e46d62958fbb457a75571ca4e0ccd27047d8ec357f7ed3",
  "repo_slug": "enzoemir1/adops-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_enzoemir1_adops_mcp_7f9133cb/readme"
}