{
"markdown": "# OrbiAds — Google Ad Manager MCP Server\n\n[English](README.md) · [Français](README.fr.md)\n\n
\n \n \n Hosted MCP for AI agents, plus a Python CLI for terminal and CI workflows.\n
\n\n[](https://modelcontextprotocol.io)\n[](https://developers.google.com/ad-manager/api/rel_notes)\n[](./version.json)\n[](https://pypi.org/project/orbiads-cli/)\n[](./docs/install/cli.md)\n[](./LICENSE)\n[](https://orbiads.com/docs)\n[](https://github.com/OrbiAds/Orbiads-GAM-MCP/stargazers)\n[](./docs/install/claude.md)\n[](./docs/install/chatgpt.md)\n[](./docs/install/gemini.md)\n[](https://glama.ai/mcp/servers/OrbiAds/Orbiads-GAM-MCP)\n[](https://mcp.so/server/OrbiAds/Orbiads-GAM-MCP)\n[](https://smithery.ai/new)\n\n**OrbiAds is a hosted Google Ad Manager MCP server** that gives AI assistants — Claude, ChatGPT, Gemini, Cursor, and OpenAI Codex — direct, natural-language access to Google Ad Manager. It covers **270+ operations** across campaigns, orders, line items, creatives, inventory, targeting, and reporting, on the **current GAM API (v202605)**, with OAuth and confirm-before-write guardrails.\n\n[**→ Get started free at orbiads.com**](https://orbiads.com) · [**★ Star this repo**](https://github.com/OrbiAds/Orbiads-GAM-MCP)\n\n---\n\n## Try in 3 Minutes\n\n### Hosted MCP, no local install\n\n1. Create a free OrbiAds account at [orbiads.com](https://orbiads.com) and connect Google Ad Manager.\n2. Add this MCP endpoint to Claude, ChatGPT, Gemini, Cursor, Codex, or Warp:\n ```text\n https://orbiads.com/mcp\n ```\n3. Ask your agent:\n ```text\n Connect to my GAM account and show me my active networks.\n ```\n\n### CLI smoke test\n\n```bash\npip install orbiads-cli\norbiads auth login\norbiads network info\n```\n\nWant a deeper setup path? Start with the [CLI guide](./docs/install/cli.md) or the [agent install guides](./docs/install/README.md).\n\n---\n\n## Trust Signals\n\n| Signal | Status | Link |\n| --- | --- | --- |\n| Public repo | MIT licensed mirror of the OrbiAds MCP distribution | [LICENSE](./LICENSE) |\n| PyPI CLI | Published as `orbiads-cli` for terminal and CI workflows | [pypi.org/project/orbiads-cli](https://pypi.org/project/orbiads-cli/) |\n| Hosted MCP | Remote Streamable HTTP endpoint with OAuth | `https://orbiads.com/mcp` |\n| Glama | Indexed MCP registry page | [glama.ai](https://glama.ai/mcp/servers/OrbiAds/Orbiads-GAM-MCP) |\n| MCP.so | Indexed MCP directory page | [mcp.so](https://mcp.so/server/OrbiAds/Orbiads-GAM-MCP) |\n| Official MCP registry | `server.json` manifest ready for registry publication | [server.json](./server.json) |\n| Smithery | Submission target prepared for hosted/external MCP listing | [smithery.ai/new](https://smithery.ai/new) |\n| Safety model | Plan → confirm → execute on write actions | [Safety docs](./docs/safety/README.md) |\n\n---\n\n## Two Ways to Connect\n\nOrbiAds offers two integration methods — choose the one that fits your workflow.\n\n### Option A: MCP Server (AI agents)\n\nConnect your AI assistant (Claude, ChatGPT, Gemini) to GAM via the hosted MCP endpoint. Conversational, guided, zero-install.\n\n```\nMCP endpoint: https://orbiads.com/mcp\n```\n\n### Option B: CLI (terminal & scripts)\n\nA lightweight Python CLI for developers, CI/CD pipelines, and headless automation. Same API, same credits, same guardrails.\n\n```bash\npip install orbiads-cli\norbiads auth login\norbiads network info\n```\n\n> [!IMPORTANT]\n> **Windows/macOS/Linux PATH Warning**: If you install the CLI via `pip` (especially with `--user`), ensure the Python scripts directory is added to your user `PATH`. Without this, your terminal and local AI agents (like Claude Code, Cursor, or Gemini) will fail to find or execute the `orbiads` command. See the [Troubleshooting section in the CLI Guide](docs/install/cli.md#troubleshooting) for quick setup commands.\n\n### Comparison\n\n| Criteria | MCP Server | CLI |\n| --- | --- | --- |\n| Interface | AI agent (Claude, ChatGPT, Gemini) | Terminal / command line |\n| Installation | URL to paste into agent settings | `pip install orbiads-cli` |\n| Authentication | OAuth via browser (automatic) | OAuth Device Flow (code displayed) |\n| Best for | Exploration, conversations, guided workflows | Scripts, CI/CD, headless automation |\n| Output format | Natural language via the agent | JSON or structured table |\n| Credits | Same consumption grid | Same consumption grid |\n| Offline | No — requires internet | No — requires internet |\n| Python required | No | Yes (3.10+) |\n\n> Both methods share the same backend, credits, and safety guardrails.\n\n### CLI Quick Reference\n\n| Command | Description |\n| --- | --- |\n| `orbiads auth login` | Authenticate via Google OAuth Device Flow |\n| `orbiads auth status` | Check authentication status |\n| `orbiads network info` | Show current GAM network details |\n| `orbiads network list` | List accessible GAM networks |\n| `orbiads orders list` | List orders in the network |\n| `orbiads line-items list --order ID` | List line items for an order |\n| `orbiads creatives list` | List creatives |\n| `orbiads inventory ad-units` | List ad units |\n| `orbiads forecast check --ad-unit ID` | Check inventory availability |\n| `orbiads report run --template ID` | Run a delivery report |\n\n> Full command reference: [orbiads.com/docs/cli/commands](https://orbiads.com/docs/cli/commands)\n\n---\n\n## Installation Guide\n\nOrbiAds offers three integration pathways depending on your environment.\n\n### 1. Zero-Install MCP Server (ChatGPT, Gemini, Claude Desktop)\nConnect your AI assistant to our hosted server using the Model Context Protocol:\n- **Claude Desktop**: Add this to your `claude_desktop_config.json`:\n ```json\n {\n \"mcpServers\": {\n \"orbiads\": {\n \"type\": \"http\",\n \"url\": \"https://orbiads.com/mcp\"\n }\n }\n }\n ```\n- **Gemini / AI Studio**: Go to Tools → MCP configuration → Add `https://orbiads.com/mcp`\n- **ChatGPT**: Go to Settings → Connectors → Add connector → MCP URL: `https://orbiads.com/mcp`\n- **GLAMA / MCP Registry**: Access, test, and connect the server directly in your browser via [glama.ai/mcp/servers/OrbiAds/Orbiads-GAM-MCP](https://glama.ai/mcp/servers/OrbiAds/Orbiads-GAM-MCP)\n- **Other environments (Cursor, Codex, Warp)**: Add the `https://orbiads.com/mcp` endpoint to your configuration and copy [`AGENTS.md`](./AGENTS.md) to your project root.\n\n### 2. Claude Code Plugin (Slash Commands)\nAdd the `/adops` command set directly into your Claude Code CLI terminal:\n```bash\nclaude plugin install orbiads\n```\n\n### 3. Agent Skills (Structured Workflows)\nInstall our markdown-based guidelines permanently into Claude Code's memory:\n1. Clone this repository locally.\n2. Run the skill installer:\n ```bash\n ./install.sh skills --copy\n ```\nThis copies our 6 consolidated skill files to your `~/.claude/skills/` directory. Claude Code will automatically leverage them to prevent hallucinations and strictly apply the plan-before-mutate workflow.\n\n→ Installation guides: [Claude](./docs/install/claude.md) · [ChatGPT](./docs/install/chatgpt.md) · [Gemini](./docs/install/gemini.md) · [OpenAI Codex](./docs/install/openai-codex.md)\n\n---\n\n## What is OrbiAds?\n\nOrbiAds is a hosted **MCP server** that connects your AI assistant directly to Google Ad Manager (GAM). Instead of clicking through the GAM interface or writing API scripts, you describe what you want in plain language — OrbiAds handles the API calls, guardrails, and audit trail.\n\n```text\nYou: \"Check inventory availability on the homepage banner for a 300x250 in France next week\"\nOrbiAds: [runs forecast] → Available: 1.2M impressions. Pressure: low. Safe to traffic.\n\nYou: \"Create the line item for Renault, €15 CPM, Monday to Friday\"\nOrbiAds: [applies guardrails] → Preview ready. Confirm to push?\n```\n\nNo scripts. No API tokens to manage. No switching tabs.\n\n---\n\n## Who is this for?\n\n- **AdOps managers** who traffic campaigns daily and want to move faster without making mistakes\n- **Publishers** who manage their own GAM network and want AI-assisted workflows\n- **Media agencies** running multiple GAM accounts who want a consistent, auditable process\n- **Developers** building AdOps automation on top of Claude, ChatGPT, or Gemini\n\n---\n\n## Supported AI Platforms\n\n| Platform | Setup guide | Mode |\n| --- | --- | --- |\n| **Claude** (Desktop / claude.ai / Claude Code) | [docs/install/claude.md](./docs/install/claude.md) | Plugin + MCP remote |\n| **ChatGPT** (Pro connector) | [docs/install/chatgpt.md](./docs/install/chatgpt.md) | MCP remote (HTTP) |\n| **Gemini** | [docs/install/gemini.md](./docs/install/gemini.md) | MCP remote |\n| **GLAMA** (MCP registry) | [glama.ai/mcp/servers/OrbiAds/Orbiads-GAM-MCP](https://glama.ai/mcp/servers/OrbiAds/Orbiads-GAM-MCP) | MCP registry |\n| **Cursor / Codex / Warp / other** | [AGENTS.md](./AGENTS.md) | AGENTS.md + MCP wiring |\n\nAll platforms connect to the same hosted MCP endpoint at `https://orbiads.com/mcp`.\n\n---\n\n## 7 Slash Commands\n\nAfter installing the plugin, these `/adops` commands are available directly in Claude Code.\n\n| Command | What it does |\n| --- | --- |\n| `/adops campaign` | Read live state, plan deployment, dry-run (`ExecutionPlan`), deploy, pause, rollback — with mandatory plan→confirm→execute gate |\n| `/adops audit` | Multi-dimensional account audit: delivery, inventory, security, creatives, billing |\n| `/adops report` | Custom reports, delivery queries, CSV export, billing summaries, forecasts |\n| `/adops deal` | PMP deals, private auctions, Marketplace PG/PD proposals |\n| `/adops creative` | Upload creatives, QA compliance, SSL validation, preview URLs, line item association |\n| `/adops inventory` | Browse ad units, manage placements and targeting taxonomy, run blueprints |\n| `/adops admin` | Teams, sites, labels, custom fields, network settings (MCP surface only) |\n\n## What's Inside (MCP Tools & Skills)\n\nThe OrbiAds surface maps the Google Ad Manager API into parent tools and hundreds of actions, organized into **6 core domain Agent Skills** plus an orchestrator, to keep context usage clean. See [`docs/tool-matrix/README.md`](./docs/tool-matrix/README.md) for the live generated tool and action counts.\n\nClick on any domain below to see which tools and capabilities are included:\n\n\n1. Campaigns & Creative QA (orbiads-campaigns)\n\n* `campaign` — Read live campaign state, plan deployment, dry-run, deploy, pause, and rollback campaigns.\n* `orders` — Create and list orders, contacts, and roles.\n* `line_items` — Define line item delivery rules, CPMs, and targeting logic.\n* `creatives` — Upload creatives (images, HTML5, video/audio) and configure native styles.\n* `creative_assets` — Manage associated image and file assets.\n* `creative_qa` — Audit click-trackers, perform compliance scans, and validate SSL certificates.\n* `creative_wrapper_skill` — Manage third-party wrappers and delivery presets.\n* `formats` — Discover and configure ad creative formats.\n* `jobs` & `gam_jobs` — Monitor async campaign compilation and deployment workflows.\n\n\n\n2. Inventory & Targeting (orbiads-inventory)\n\n* `inventory` — Retrieve ad unit trees, sizes, and generate ads.json manifests.\n* `placements` — Create, update, and list ad placement groups.\n* `targeting` — Manage custom targeting keys/values, countries, and categories.\n* `audiences` — Retrieve and modify first-party audience segments.\n* `blueprint` — Generate and push structured network inventory blueprints.\n\n\n\n3. Reporting & Forecasting (orbiads-reporting)\n\n* `reporting` — Run custom reports from templates, check line item delivery, and integrate GA4.\n* `preview` — Verify inventory coverage and export preview URLs.\n* `pql` — Run raw PQL database queries.\n\n\n\n4. Programmatic Deals (orbiads-deals)\n\n* `deals` — Manage PMP deals, private auctions, and marketplace buyers.\n* `companies` — Manage agency and advertiser company profiles.\n\n\n\n5. Network Admin (orbiads-admin)\n\n* `gam_admin` — Access advanced fields, network labels, teams, and site records.\n* `gam_features` — Query active Google Ad Manager beta and system features.\n* `network` — List accessible networks and switch active network context.\n* `settings` — Configure default CPMs, pacing, and brand naming templates.\n* `tenant_catalog` — Access tenant-specific catalogs.\n\n\n\n6. Audits & Billing (orbiads-audit)\n\n* `audit_skill` — Run automated security, hygiene, and wrapper coverage audits.\n* `billing` — Fetch credit balances and transaction histories.\n* `audit` — Search network audit logs.\n\n\n> See [`docs/tool-matrix/README.md`](./docs/tool-matrix/README.md) for the complete parity matrix detailing exact costs, writes, and parameters for all 270+ actions.\n\n---\n\n## Safety by Design\n\nEvery write action requires an explicit `ExecutionPlan` preview and confirmation token. No campaign goes live by accident.\n\n- **Plan-before-mutate** on campaign, deal, and product writes — preview the signed `ExecutionPlan` before you push\n- **Dry-run mode** on all deployment actions — `confirmationToken` TTL 300 seconds\n- **Forecast gate** before inventory commits — availability verified upfront\n- **Audit trail** on every action — who did what, when, with what result\n- **Credit guard** — read operations are always free, writes deduct credits transparently\n\n---\n\n## Quick Start (3 steps)\n\n### 1. Create your free account\n\nGo to [orbiads.com](https://orbiads.com) and sign up. You get **5 free credits** — no credit card required.\n\n### 2. Connect Google Ad Manager\n\nFrom the OrbiAds dashboard, click **Connect GAM** and authorize with your Google account. OrbiAds uses OAuth — your GAM credentials never leave Google's infrastructure.\n\n### 3. Configure your AI assistant\n\nPick your platform and follow the guide:\n\n- [Claude setup →](./docs/install/claude.md)\n- [ChatGPT setup →](./docs/install/chatgpt.md)\n- [Gemini setup →](./docs/install/gemini.md)\n- [Other tools (Cursor, Codex, Warp) →](./AGENTS.md)\n\nThen start with:\n\n> *\"Connect to my GAM account and show me my active networks\"*\n\n---\n\n## MCP Server Details\n\n| Property | Value |\n| --- | --- |\n| Endpoint | `https://orbiads.com/mcp` |\n| Transport | `streamable-http` (default) · `sse` |\n| Auth | OAuth 2.0 — Google account via OrbiAds |\n| GAM API version | `v202605` |\n| MCP Protocol | `2025-03-26` |\n\n---\n\n## Repository Structure\n\n```text\nskills/ ← orchestrator skill + 6 consolidated dual-surface domain skills (generated)\n Each domain skill has SKILL.md (thin) + references/actions.md (full catalogue)\ncommands/ ← 7 /adops slash commands for Claude Code\nagents/ ← Parallel audit subagents (audit-delivery, audit-inventory, …)\nhooks/ ← Claude Code hooks (hooks.json)\ncli/ ← OrbiAds CLI package (pip install orbiads-cli)\ndocs/ ← Installation guides, tool matrix, custom-skill authoring guide\n_docs/ ← Internal: legacy tool mapping, anti-collision rules\n.claude-plugin/ ← Claude plugin manifest (plugin.json, marketplace.json)\nAGENTS.md ← Cross-LLM contract for Cursor, Codex, Gemini, Warp, etc.\nCLAUDE.md ← Claude Code project guidance\n```\n\n> Skills and the tool matrix are **generated** from the backend catalogue — do not hand-edit them. See `CLAUDE.md` for the generated vs. hand-authored breakdown.\n\n---\n\n## Pricing\n\n| Plan | Price | Credits |\n| --- | --- | --- |\n| Trial | Free | 5 credits (no card) |\n| Starter | €39/month | 50 credits/month |\n| Early Access | **€29/month** ← locked for life | 50 credits/month |\n| Pack S | €29 one-time | +50 credits |\n| Pack L | €45 one-time | +100 credits |\n\nReads are always free. Credits are only consumed on write and deploy operations.\n\n[**Start free →**](https://orbiads.com)\n\n---\n\n## License\n\nThe contents of this repository — distribution scaffold, skills, agents, workflows, JSON schemas, CLI client, platform integration manifests, documentation, and examples — are released under the [MIT License](./LICENSE).\n\nThe OrbiAds MCP server backend and Cloud Run services that the hosted endpoint at `https://orbiads.com/mcp` connects to are NOT in this repository and are governed by separate proprietary terms — [see terms at orbiads.com](https://orbiads.com).\n\n
![\"OrbiAds](\"./logo/terminal_mockup.png\"){kind=logo}
\n ![\"OrbiAds](\"./logo/orbiads-logo-brand.png\"){kind=logo}
\n