@aligulzar729/google-ads-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Gulzar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,391 @@
+# google-ads-mcp
+
+[![CI](https://github.com/aligulzar729/google-ads-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/aligulzar729/google-ads-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@aligulzar729/google-ads-mcp.svg)](https://www.npmjs.com/package/@aligulzar729/google-ads-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Run your Google Ads account from Claude, Codex, or any AI assistant, in plain English.
+
+Ask for a report, launch a campaign, tune bids and budgets, manage keywords, or build Performance Max assets, all by chatting. It's an [MCP](https://modelcontextprotocol.io) server, so it plugs into any AI harness that speaks MCP: Claude Code, Claude Desktop, OpenAI Codex, Cursor, LibreChat, and others.
+
+The important part: reads are free and can never spend, and every write **previews first**. The assistant shows you the exact values and asks you to type **yes** or **ok** in chat; only then does it apply with `confirmed:true` and `user_confirmation`. New campaigns start paused. You get an AI copilot for Google Ads without pretending the model is a free pass on your budget.
+
+> **Money and residual risk:** once something is enabled or a budget goes up, Google can spend real money. Previews and yes/ok are guardrails, not a bank lock, MCP cannot force a human click, and a sloppy model could invent approval. Read the preview. If you would not hit Apply in the Google Ads UI, do not type yes here. See [About money](#about-money) and [SECURITY.md](SECURITY.md).
+
+```
+You:  How did my campaigns do last month?
+AI:   (pulls a report: clicks, cost, conversions, ROAS by campaign)
+
+You:  Create a paused search campaign "Summer Sale" with a $20/day budget.
+AI:   (shows a preview of exactly what it will create)
+      Type yes or ok to create it, or anything else to cancel.
+You:  yes
+AI:   Created "Summer Sale" (PAUSED). It won't serve until you enable it.
+```
+
+## Quick start
+
+```bash
+# 1) Credentials: developer token + OAuth client + refresh token + customer id
+#    (see Credentials below). Put them in your shell or MCP client env.
+
+# 2) Run via npx (no install), stdio is the default
+npx -y @aligulzar729/google-ads-mcp --help
+
+# 3) Or clone and develop
+git clone https://github.com/aligulzar729/google-ads-mcp.git
+cd google-ads-mcp
+npm ci
+cp .env.example .env   # fill in values
+npm run dev:stdio      # or: npm run dev:http
+```
+
+Node **22.5+** is required (HTTP mode uses Node's built-in SQLite).
+
+## What it can do
+
+- **Reporting**: campaign performance, Search impression share, Performance Max asset groups, and raw GAQL for anything else. It looks up real field names first, so queries don't fail on guessed fields.
+- **Campaigns**: create Search, Display, Demand Gen, Video, App, Shopping, and Performance Max campaigns; rename, set dates and networks, pause and resume, set budgets and bidding strategies, and target by location, language, and schedule.
+- **Ad groups and ads**: manage ad groups and build ads per channel (responsive search, responsive display, HTML5, Demand Gen, video, app, shopping).
+- **Keywords**: list with quality score, add positive or negative keywords, change bids and status.
+- **Performance Max**: create asset groups from text and images, update or delete them, add more images, list and remove assets.
+- **Accounts**: check the connection, list the accounts you can reach, switch the active one, and read an audit trail of every change.
+
+## What this is not
+
+- **Not the Google Ads UI.** There is no full visual editor, no Auction Insights dashboard, no Billing center. For some jobs you still open ads.google.com.
+- **Not an autopilot.** It does not decide strategy for you, watch ROAS overnight, or "just run ads." You (or a human who knows the account) still choose what to build and what to enable.
+- **Not a guarantee of perfect model behavior.** Tool text tells the assistant to preview and wait for your yes/ok. Most models will. Some will not. Stay in the loop on anything that spends or deletes.
+- **Not a substitute for access control.** Whoever can talk to this server with your credentials can attempt the same changes you can. Use least-privilege Google users, and do not point a public bot at a high-spend account for fun.
+- **Not offline magic.** It talks to the real Google Ads API. Bad GAQL, wrong customer id, or a Testing-mode OAuth app will fail the same way they would in any other client.
+
+If you want a report in chat, a careful campaign draft, or help wiring keywords and P-Max assets with a human still holding the wheel, you are in the right place. If you want unsupervised budget AI, you are not.
+
+## About money
+
+Reads never cost anything. Writes can.
+
+| Action | Money impact |
+|--------|----------------|
+| Reports, lookups, list ads, connection status | None. Free. |
+| Create campaign / P-Max asset group | **Paused by default**, no serving, no spend until something is enabled. |
+| Raise daily budget, change bids, enable a campaign or ad group | Can spend as soon as Google serves. |
+| Pause or remove | Stops or deletes serving; removes are permanent for that entity. |
+
+A few blunt habits that save people pain:
+
+- Start on a **test or low-budget** account while you learn the tools.
+- Treat **yes** like approving a wire: skim the preview numbers (budget, bid, status) before you type it.
+- Prefer **PAUSED** creates, then enable only what you meant to turn on.
+- Shared budgets are shared, changing one campaign's budget can hit every campaign on that budget (the tools warn when they can).
+- Disabling chat confirm (`REQUIRE_USER_CONFIRMATION=false`) is for trusted automation only. On a live account with real spend, leave it on.
+
+You are responsible for the Google Ads account and any charges that come from it. This project is MIT software that talks to Google's API; it does not pay your media bill and it does not absorb mistakes.
+
+## Safe by default
+
+- Reads never cost money. Reporting, lookups, and status checks are always free.
+- Every write **previews first**. The model must show you the values and ask you to type **yes** or **ok**. Apply requires `confirmed:true` and `user_confirmation` `"yes"` or `"ok"` (`REQUIRE_USER_CONFIRMATION`, default on).
+- New campaigns and Performance Max asset groups are created **paused**, so they never serve or spend until you turn them on.
+- Deletes show a clear warning before they run (gated by `REQUIRE_USER_CONFIRMATION`, default on).
+- Every applied change is recorded in a durable audit log.
+- HTTP mode rate-limits OAuth and `/mcp` per client IP (process-local; put a reverse proxy in front for multi-replica).
+
+Trusted headless automation only: set `REQUIRE_USER_CONFIRMATION=false` so one-shot `confirmed:true` works without a chat yes/ok. Do that only when you already trust the caller with the account.
+
+## Requirements
+
+- Node 22.5 or newer.
+- Google Ads API credentials (see [Credentials](#credentials)).
+
+No native build step and no database to run: it uses Node's built-in SQLite, so `npx` just works.
+
+## Add it to your AI harness
+
+For a single account on your own machine, most people use the stdio mode below. For a shared, multi-user deployment where each person signs in with their own Google account, see [Hosted, multi-user](#hosted-multi-user).
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+<br>
+
+Add it from the CLI (put the server name right after `add`, then the env vars):
+
+```bash
+claude mcp add google-ads \
+  --env GOOGLE_ADS_DEVELOPER_TOKEN=... \
+  --env GOOGLE_OAUTH_CLIENT_ID=... \
+  --env GOOGLE_OAUTH_CLIENT_SECRET=... \
+  --env GOOGLE_ADS_REFRESH_TOKEN=... \
+  --env GOOGLE_ADS_CUSTOMER_ID=... \
+  -- npx -y @aligulzar729/google-ads-mcp
+```
+
+Or add it to `.mcp.json` (shared with a project) or `~/.claude.json` (just you):
+
+```json
+{
+  "mcpServers": {
+    "google-ads": {
+      "command": "npx",
+      "args": ["-y", "@aligulzar729/google-ads-mcp"],
+      "env": {
+        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
+        "GOOGLE_OAUTH_CLIENT_ID": "...",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "...",
+        "GOOGLE_ADS_REFRESH_TOKEN": "...",
+        "GOOGLE_ADS_CUSTOMER_ID": "..."
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+<br>
+
+Edit the config file (Settings, then Developer, then Edit Config), or open it directly:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "google-ads": {
+      "command": "npx",
+      "args": ["-y", "@aligulzar729/google-ads-mcp"],
+      "env": {
+        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
+        "GOOGLE_OAUTH_CLIENT_ID": "...",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "...",
+        "GOOGLE_ADS_REFRESH_TOKEN": "...",
+        "GOOGLE_ADS_CUSTOMER_ID": "..."
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+</details>
+
+<details>
+<summary><b>OpenAI Codex</b></summary>
+
+<br>
+
+Add it from the CLI:
+
+```bash
+codex mcp add google-ads -- npx -y @aligulzar729/google-ads-mcp
+```
+
+Or edit `~/.codex/config.toml` directly. The table name must be `mcp_servers` with an underscore:
+
+```toml
+[mcp_servers.google-ads]
+command = "npx"
+args = ["-y", "@aligulzar729/google-ads-mcp"]
+env = { GOOGLE_ADS_DEVELOPER_TOKEN = "...", GOOGLE_OAUTH_CLIENT_ID = "...", GOOGLE_OAUTH_CLIENT_SECRET = "...", GOOGLE_ADS_REFRESH_TOKEN = "...", GOOGLE_ADS_CUSTOMER_ID = "..." }
+```
+</details>
+
+<details>
+<summary><b>LibreChat (hosted, multi-user)</b></summary>
+
+<br>
+
+LibreChat connects over HTTP and lets each user sign in with their own Google account, so you run the server yourself (see [Hosted, multi-user](#hosted-multi-user)) and point LibreChat at it. A ready-to-use `librechat.yaml` snippet ships in this repo:
+
+```yaml
+mcpServers:
+  GoogleAds:
+    type: streamable-http
+    url: "https://your-subdomain.example.com/mcp"
+    startup: false
+```
+
+`startup: false` matters: this server uses OAuth, so it should connect when a user first signs in, not at boot. Also add the host to `mcpSettings.allowedDomains` in `librechat.yaml`. Users then click Connect in chat and approve at Google. Nothing to paste.
+</details>
+
+<details>
+<summary><b>Cursor / VS Code</b></summary>
+
+<br>
+
+Add an MCP server entry (Cursor: Settings → MCP; VS Code Copilot: MCP config) equivalent to:
+
+```json
+{
+  "mcpServers": {
+    "google-ads": {
+      "command": "npx",
+      "args": ["-y", "@aligulzar729/google-ads-mcp"],
+      "env": {
+        "GOOGLE_ADS_DEVELOPER_TOKEN": "...",
+        "GOOGLE_OAUTH_CLIENT_ID": "...",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "...",
+        "GOOGLE_ADS_REFRESH_TOKEN": "...",
+        "GOOGLE_ADS_CUSTOMER_ID": "..."
+      }
+    }
+  }
+}
+```
+
+Exact JSON key names vary slightly by client (`mcpServers` vs `servers`); keep `command` / `args` / `env` the same.
+</details>
+
+<details>
+<summary><b>Any other MCP client</b></summary>
+
+<br>
+
+Single user, over stdio: run `npx -y @aligulzar729/google-ads-mcp` with the five `GOOGLE_ADS_*` / `GOOGLE_OAUTH_*` env vars set, using whatever `command` / `args` / `env` shape your client expects.
+
+Multi-user, over HTTP: run it in `--http` mode behind HTTPS and point your client at `https://<host>/mcp`. Any client that supports streamable-http with OAuth (dynamic client registration plus PKCE) can connect. See [Hosted, multi-user](#hosted-multi-user).
+</details>
+
+## Credentials
+
+Three values are always required, because they identify the app (not the user):
+
+- `GOOGLE_ADS_DEVELOPER_TOKEN`: from your Google Ads manager account, under API Center. Apply for Standard Access before you run production volume.
+- `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET`: an OAuth client from a Google Cloud project that has the Google Ads API enabled.
+
+For local (stdio) use, add one account's own credentials:
+
+- `GOOGLE_ADS_REFRESH_TOKEN`: a refresh token for a Google account with access to the ads account. You can mint one with the [OAuth 2.0 Playground](https://developers.google.com/oauthplayground) using the `https://www.googleapis.com/auth/adwords` scope.
+- `GOOGLE_ADS_CUSTOMER_ID`: the 10-digit account id, no dashes.
+- `GOOGLE_ADS_LOGIN_CUSTOMER_ID`: optional, set it to your manager (MCC) id if you access clients through a manager account.
+
+Keep the OAuth app in the **In Production** publishing status. In Testing, refresh tokens expire after 7 days.
+
+For hosted (http) use you don't set a refresh token at all. Users authorize themselves in the browser and the server stores each token encrypted. See below.
+
+## Configuration
+
+Everything is set through environment variables, and every setting can also be passed as a command-line flag (useful in a client's `args` or a launch command). The flag is the env var name, lowercased, with dashes for underscores:
+
+```bash
+npx -y @aligulzar729/google-ads-mcp \
+  --app-name="Acme Ads" \
+  --log-level=debug \
+  --no-require-user-confirmation      # trusted automation only
+```
+
+In a client config, add them to `args`:
+
+```json
+"args": ["-y", "@aligulzar729/google-ads-mcp", "--app-name=Acme Ads"]
+```
+
+| Setting | Env var (or flag) | Notes |
+|---------|-------------------|-------|
+| App name | `APP_NAME` / `--app-name` | shown on the OAuth consent and error pages |
+| Log level | `LOG_LEVEL` / `--log-level` | `debug`, `info`, `warn`, `error` |
+| Require confirmation | `REQUIRE_USER_CONFIRMATION` / `--no-require-user-confirmation` | default on; gates every write, including deletes; off only for trusted headless |
+| HTTP port | `PORT` / `--port` | default 3001 |
+
+Credentials and keys (`GOOGLE_ADS_*`, `GOOGLE_OAUTH_*`, `TOKEN_ENC_KEY`) work as flags too, but prefer env vars for secrets: flags can show up in the process list.
+
+## Hosted, multi-user
+
+In `--http` mode the server is its own OAuth 2.1 authorization server that proxies Google. Each user signs in once, and their Google refresh token is stored encrypted on the server and never handed back to the client. This is how you offer Google Ads to a whole team from a shared chat app like LibreChat.
+
+Run it (behind HTTPS, on its own subdomain):
+
+```bash
+npx -y @aligulzar729/google-ads-mcp --http
+```
+
+Extra environment it needs in this mode:
+
+- `TOKEN_ENC_KEY`: 32-byte base64 key that encrypts stored refresh tokens. Generate with `openssl rand -base64 32`. Keep it stable and secret; rotating it invalidates every stored authorization.
+- `PUBLIC_BASE_URL`: the public HTTPS base URL of this instance, for example `https://ads.example.com`. Register `${PUBLIC_BASE_URL}/auth/callback` as a redirect URI on your Google OAuth client.
+- `ALLOWED_REDIRECT_ORIGINS`: comma-separated allowlist of client origins allowed to complete the OAuth flow, for example `https://chat.example.com`. This is what stops a phished authorize link from delivering a code to an attacker.
+- `PORT`: defaults to 3001.
+- `AUDIT_DB_PATH`: where the audit log and encrypted authorizations live. Mount a volume so it survives restarts.
+
+A `Dockerfile` and `docker-compose.yml` are included for a container deployment.
+
+### Docker Compose (HTTP)
+
+```bash
+cp .env.example .env
+# set GOOGLE_ADS_DEVELOPER_TOKEN, GOOGLE_OAUTH_*, TOKEN_ENC_KEY,
+# PUBLIC_BASE_URL=https://ads.example.com, ALLOWED_REDIRECT_ORIGINS=https://chat.example.com
+
+docker compose up -d --build
+curl -sS http://127.0.0.1:3001/healthz
+```
+
+Point your reverse proxy (TLS) at `127.0.0.1:3001`. The **whole subdomain** must reach this container: OAuth discovery, `/authorize`, `/token`, and `/mcp` all live on the same host (`PUBLIC_BASE_URL`). Back up the `ads_data` volume (audit log + encrypted authorizations).
+
+## Tools
+
+Seven tools, each takes an `action`:
+
+| Tool | Actions | What it covers |
+|------|---------|----------------|
+| `google_ads_account` | `status`, `list`, `switch`, `audit` | connection and token check, accounts you can reach, switch the active account, read the audit trail |
+| `google_ads_report` | `campaign_performance`, `impression_share`, `asset_group`, `gaql`, `metadata` | curated campaign report, Search impression share, Performance Max asset-group performance, raw GAQL, and field discovery |
+| `google_ads_campaign` | `create`, `update`, `status`, `budget`, `bidding`, `targeting` | create any campaign type, rename and set dates and networks, pause and resume, budgets, bidding, and location/language/schedule targeting |
+| `google_ads_ad_group` | `create`, `update`, `status`, `list_ads`, `add_ad`, `ad_status` | manage ad groups and their ads, including per-channel ad builders via `ad_type` |
+| `google_ads_keyword` | `list`, `add`, `update` | list with quality score, add positive or negative, change bid or status |
+| `google_ads_pmax` | `create_asset_group`, `asset_group`, `add_images`, `list_assets`, `remove_asset` | create an asset group from text and images (images are required up front and it starts paused), update or delete a group, add images, list and remove assets |
+| `google_ads_lookup` | `location`, `language` | turn a location or language name into the numeric id that targeting and geo reports need |
+
+A few things worth knowing: ROAS is computed as conversion value over cost. Average Position is gone (Google removed it), so use `impression_share`. Performance Max has no ad-level reporting, so use `gaql` on its asset groups.
+
+## Big reports and pagination
+
+Reports are bounded per response and paged without hitting Google again:
+
+1. The first call fetches one bounded page and asks Google for the true total row count in the same request, so a capped report reads `top 200 of 47,310` instead of quietly cutting off.
+2. Leftover rows are parked in a short-lived (about 5 minutes), per-account cache.
+3. If more rows remain, the reply ends with a `cursor`. The model asks whether you want the rest, then continues from cache with zero extra Google calls, so paging can't cause rate limiting.
+
+One report run is bounded to `limit` rows by design. To go wider, tighten the query or aggregate in GAQL. For genuinely huge extracts, use an export rather than inline rows.
+
+## Scheduled and unattended use
+
+Reporting is read-only and retried, so it's reliable for cron and scheduled jobs once the OAuth app is In Production.
+
+- A dead refresh token returns a clear "reconnect Google Ads" message and is written to the audit log with `category:"auth"`, so you can alert on it.
+- Call `google_ads_account` with `status` at the start of a routine to fail fast.
+- Quota and rate errors are retried with backoff, and if they still fail you get a clear "needs Standard Access" message.
+
+## Troubleshooting
+
+| Symptom | What to try |
+|---------|-------------|
+| Refresh token dies after ~7 days | OAuth app is still in **Testing**. Publish it to **In Production**. |
+| `PERMISSION_DENIED` / empty account list | User lacks access to that customer id; or set `GOOGLE_ADS_LOGIN_CUSTOMER_ID` to the MCC id when accessing clients through a manager. |
+| Quota / rate errors | Developer token may need **Standard Access**. Reads are retried with backoff. |
+| "user_confirmation" / confirmed rejected | Call once without `confirmed` to preview, ask the user to type yes or ok, then re-call with `confirmed:true` and `user_confirmation:"yes"` (or `"ok"`). |
+| "not connected" / reconnect message | Refresh token revoked; re-auth (HTTP) or mint a new refresh token (stdio). |
+| HTTP container exits on boot | Missing `TOKEN_ENC_KEY`, `PUBLIC_BASE_URL`, or `ALLOWED_REDIRECT_ORIGINS`. Check logs. |
+| OAuth works but LibreChat never connects | `startup: false` on the MCP server entry; host in `allowedDomains`; URL must be the public `/mcp` path. |
+
+## Notes
+
+- The underlying client, `google-ads-api` (Opteo), is the community Node library for the advertiser API; Google doesn't ship an official one. It targets API v23. The high-level query and mutate calls used here are version-agnostic, but check method signatures if you upgrade the library.
+- Error messages and tool text are in English.
+- See [SECURITY.md](SECURITY.md) for disclosure, residual risk, and key-compromise playbook. See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## Acknowledgments
+
+This project is built on [`google-ads-api`](https://github.com/Opteo/google-ads-api), the community Node client for the Google Ads API maintained by the team at [Opteo](https://opteo.com). Google ships no official Node library for the advertiser API, and Opteo's package fills that gap with a well-typed, carefully maintained interface that handles the hard parts (OAuth, GAQL, mutates, and the Google Ads protobufs) so this server does not have to. A sincere thank you to the Opteo maintainers and contributors: this MCP server stands on their work.
+
+## License
+
+MIT
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).