@aligulzar729/google-ads-mcp 0.2.0 → 0.4.0

package/README.md

@@ -10,7 +10,7 @@ Ask for a report, launch a campaign, tune bids and budgets, manage keywords, or
 
 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).
+> **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 [Money and safety](#money-and-safety) and [SECURITY.md](SECURITY.md).
 
 ```
 You:  How did my campaigns do last month?
@@ -23,6 +23,27 @@ You:  yes
 AI:   Created "Summer Sale" (PAUSED). It won't serve until you enable it.
 ```
 
+## Contents
+
+- [Quick start](#quick-start)
+- [What it can do](#what-it-can-do)
+- [What this is not](#what-this-is-not)
+- [Money and safety](#money-and-safety)
+- [Add it to your AI harness](#add-it-to-your-ai-harness)
+- [Credentials](#credentials) (and [Getting a refresh token](#getting-a-refresh-token-oauth-playground))
+- [Configuration](#configuration) (and [all environment variables](#all-environment-variables))
+- [Hosted, multi-user](#hosted-multi-user) (and [LibreChat on the same host](#librechat-on-the-same-host-no-public-url))
+- [Tools](#tools)
+- [Coverage](#coverage)
+- [Big reports and pagination](#big-reports-and-pagination)
+- [Scheduled and unattended use](#scheduled-and-unattended-use)
+- [Troubleshooting](#troubleshooting)
+- [Notes](#notes)
+- [Acknowledgments](#acknowledgments)
+- [Disclaimer](#disclaimer)
+- [License](#license)
+- [Contributing](#contributing)
+
 ## Quick start
 
 ```bash
@@ -40,16 +61,27 @@ 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).
+Node **22.5+** is required. There is no native build step and no database to run: HTTP mode uses Node's built-in SQLite, so `npx` just works.
 
 ## 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.
+- **Campaigns**: create Search, Display, Demand Gen, App, Shopping, and Performance Max campaigns (use Demand Gen for YouTube; Google no longer lets the API create Video 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.
+- **Accounts**: check the connection and list the accounts you can reach; on the hosted (HTTP) server, also switch the active account and read an audit trail of every change.
+
+### What it can't do
+
+- **Conversion tracking.** Creating or editing conversion actions and importing offline conversions (it reads conversion metrics, but doesn't set them up).
+- **Audiences and bid adjustments.** Remarketing or customer-match lists, audience targeting, and device, demographic, or audience bid modifiers. Targeting here is location, language, and ad schedule only.
+- **Search ad assets / extensions.** Sitelinks, callouts, structured snippets, call, price, and promotion assets (Performance Max text and image assets are supported).
+- **Account structure and budgets.** Creating customer accounts, managing an MCC hierarchy, or setting up billing and account-level budget orders.
+- **Experiments, drafts, and recommendations.** A/B experiments, campaign drafts, and applying Google's optimization-score recommendations.
+- **Shared library and labels.** Shared budgets, negative-keyword and placement-exclusion sets, and labels.
+- **Keyword Planner.** Keyword ideas and traffic forecasts.
+- **External links.** Merchant Center, Analytics, and YouTube account links (Shopping and Performance Max assume these already exist).
 
 ## What this is not
 
@@ -61,9 +93,9 @@ Node **22.5+** is required (HTTP mode uses Node's built-in SQLite).
 
 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
+## Money and safety
 
-Reads never cost anything. Writes can.
+Reads never cost anything. Writes can, and every write **previews first**: the model shows the exact values and asks you to type **yes** or **ok**; apply then requires `confirmed:true` and `user_confirmation` `"yes"` or `"ok"` (`REQUIRE_USER_CONFIRMATION`, default on).
 
 | Action | Money impact |
 |--------|----------------|
@@ -72,33 +104,18 @@ Reads never cost anything. Writes can.
 | 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:
+More guardrails: new campaigns and P-Max asset groups start **paused**; deletes show a clear warning first (also gated by `REQUIRE_USER_CONFIRMATION`); every applied change lands in a durable audit log; and HTTP mode rate-limits OAuth and `/mcp` per client IP (process-local, put a reverse proxy in front for multi-replica).
+
+Habits that save 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.
+- Shared budgets are shared: changing one campaign's budget can hit every campaign on that budget (the tools warn when they can).
 
-## Safe by default
+`REQUIRE_USER_CONFIRMATION=false` disables the chat yes/ok so one-shot `confirmed:true` works, for trusted headless automation only. On a live account with real spend, leave it on.
 
-- 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.
+You are responsible for the Google Ads account and any charges from it. This is MIT software that talks to Google's API; it does not pay your media bill and does not absorb mistakes.
 
 ## Add it to your AI harness
 
@@ -199,7 +216,7 @@ env = { GOOGLE_ADS_DEVELOPER_TOKEN = "...", GOOGLE_OAUTH_CLIENT_ID = "...", GOOG
 
 <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:
+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:
 
 ```yaml
 mcpServers:
@@ -207,9 +224,15 @@ mcpServers:
     type: streamable-http
     url: "https://your-subdomain.example.com/mcp"
     startup: false
+    requiresOAuth: true
 ```
 
-`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.
+Two settings matter:
+
+- `requiresOAuth: true` declares this a per-user OAuth server. Without it, LibreChat tries to auto-detect OAuth by opening an unauthenticated connection to list tools, which always fails on an auth-walled server and fills your logs with `OAuth not supported in unauthenticated discovery` and repeated `Reinspection failed ... timeout`. The flag skips that probe and shows the sign-in prompt directly.
+- `startup: false` connects on first use, not at boot, since there is no user to authorize at startup.
+
+Also add the host to `mcpSettings.allowedDomains` in `librechat.yaml`. Users then click Connect in chat and approve at Google. Nothing to paste. To run LibreChat and this server on one machine with no public URL, see [LibreChat on the same host](#librechat-on-the-same-host-no-public-url).
 </details>
 
 <details>
@@ -259,17 +282,33 @@ Three values are always required, because they identify the app (not the user):
 
 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.
+- `GOOGLE_ADS_REFRESH_TOKEN`: a refresh token for a Google account with access to the ads account. See [Getting a refresh token](#getting-a-refresh-token-oauth-playground) below.
+- `GOOGLE_ADS_CUSTOMER_ID`: the account you act on, 10 digits with no dashes. Its campaigns and reports are what you read and change.
+- `GOOGLE_ADS_LOGIN_CUSTOMER_ID`: optional. The manager (MCC) account you reach that account *through*, if any.
+
+These two trip everyone up, so plainly: `CUSTOMER_ID` is **which account to act on**, `LOGIN_CUSTOMER_ID` is **which manager to go through to reach it**. A manager (MCC) account holds no campaigns itself; it just grants access to the client accounts under it. So:
+
+- Your Google user has **direct** access to the account (it shows as `[client]` in `google_ads_account list`): set `CUSTOMER_ID` to it and **leave `LOGIN_CUSTOMER_ID` empty**.
+- You only reach the account **through a manager**: set `CUSTOMER_ID` to the client account and `LOGIN_CUSTOMER_ID` to that **manager's** id, never to the client id, and never to a manager that does not actually own the client (both cause `PERMISSION_DENIED`).
 
 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.
 
+### Getting a refresh token (OAuth Playground)
+
+For stdio mode you supply one account's refresh token. Two settings are what everyone gets wrong, so both steps below are required:
+
+1. **Add the Playground redirect to your OAuth client.** In Google Cloud Console, open your OAuth client (the one whose id and secret you use) under APIs & Services, then Credentials. Under **Authorized redirect URIs**, add `https://developers.google.com/oauthplayground` and save. Miss this and the Playground fails with `redirect_uri_mismatch`.
+2. **Use your own client in the Playground.** Open the [OAuth 2.0 Playground](https://developers.google.com/oauthplayground), click the **gear** (top right), check **Use your own OAuth credentials**, and paste the same client id and secret. Miss this and the token is minted for Google's demo client, which later fails with `unauthorized_client`.
+3. **Authorize the Ads scope.** In the left panel under "Input your own scopes", enter `https://www.googleapis.com/auth/adwords`, click **Authorize APIs**, and sign in with the Google account that can reach the ads account.
+4. **Exchange for the token.** Click **Exchange authorization code for tokens** and copy the `refresh_token` into `GOOGLE_ADS_REFRESH_TOKEN`.
+
+A token works only when both are true: it was minted by *your* client (step 2) and *your* client permits the Playground redirect (step 1). The Playground redirect is only needed for minting, so you can remove it from the client afterward; it is separate from the `PUBLIC_BASE_URL/auth/callback` redirect that http mode registers.
+
 ## 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:
+Everything is set through environment variables. Every setting can also be passed as a command-line flag: the flag is the env var name, lowercased, with dashes for underscores. A bare `--flag` sets `true`, and `--no-flag` sets `false`. Flags are handy in a client's `args` or a launch command:
 
 ```bash
 npx -y @aligulzar729/google-ads-mcp \
@@ -278,20 +317,47 @@ npx -y @aligulzar729/google-ads-mcp \
   --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 |
+Prefer env vars for secrets: flags can show up in the process list.
+
+### All environment variables
+
+**App identity, required in both modes.** These identify the app, not the user.
 
-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.
+| Env var | Flag | Description |
+|---------|------|-------------|
+| `GOOGLE_ADS_DEVELOPER_TOKEN` | `--google-ads-developer-token` | Google Ads API developer token, from your manager account API Center. |
+| `GOOGLE_OAUTH_CLIENT_ID` | `--google-oauth-client-id` | OAuth client id from a Google Cloud project with the Google Ads API enabled. |
+| `GOOGLE_OAUTH_CLIENT_SECRET` | `--google-oauth-client-secret` | OAuth client secret. |
+
+**Behavior, both modes.**
+
+| Env var | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `APP_NAME` | `--app-name` | `Google Ads MCP` | Name shown on the OAuth consent and error pages. |
+| `LOG_LEVEL` | `--log-level` | `info` | `debug`, `info`, `warn`, or `error`. |
+| `REQUIRE_USER_CONFIRMATION` | `--no-require-user-confirmation` | on | Gates every write, including deletes. Turn off only for trusted headless automation. |
+
+**stdio mode, single user.** One account's own credentials.
+
+| Env var | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `GOOGLE_ADS_REFRESH_TOKEN` | `--google-ads-refresh-token` | empty | Refresh token for a Google account with access to the ads account. See [Getting a refresh token](#getting-a-refresh-token-oauth-playground). |
+| `GOOGLE_ADS_CUSTOMER_ID` | `--google-ads-customer-id` | empty | The account to act on (10 digits, no dashes). |
+| `GOOGLE_ADS_LOGIN_CUSTOMER_ID` | `--google-ads-login-customer-id` | empty | The manager (MCC) to reach it through; leave empty for direct access. See [Credentials](#credentials). |
+
+**http mode, hosted and multi-user.** Per-user credentials come from each user's browser sign-in, so you do not set a refresh token here.
+
+| Env var | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `PORT` | `--port` | `3001` | Listen port. |
+| `PUBLIC_BASE_URL` | `--public-base-url` | required | Public base URL of this instance. Register `PUBLIC_BASE_URL/auth/callback` as a redirect URI on the Google OAuth client. |
+| `TOKEN_ENC_KEY` | `--token-enc-key` | required | 32-byte base64 key (`openssl rand -base64 32`) that encrypts stored refresh tokens. Keep it stable and secret. |
+| `ALLOWED_REDIRECT_ORIGINS` | `--allowed-redirect-origins` | required | Comma-separated allowlist of client origins allowed to complete the OAuth flow, for example `https://chat.example.com`. |
+| `AUDIT_DB_PATH` | `--audit-db-path` | `./data/audit.db` | Where the audit log and encrypted authorizations live. Mount a volume so it survives restarts. |
 
 ## Hosted, multi-user
 
@@ -303,13 +369,7 @@ Run it (behind HTTPS, on its own subdomain):
 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.
+Beyond the shared app credentials, this mode needs `TOKEN_ENC_KEY`, `PUBLIC_BASE_URL`, and `ALLOWED_REDIRECT_ORIGINS`, plus optional `PORT` and `AUDIT_DB_PATH` (see [All environment variables](#all-environment-variables)). Two things worth calling out: register `PUBLIC_BASE_URL/auth/callback` as a redirect URI on your Google OAuth client, and `ALLOWED_REDIRECT_ORIGINS` is the allowlist that stops a phished authorize link from delivering a code to an attacker.
 
 A `Dockerfile` and `docker-compose.yml` are included for a container deployment.
 
@@ -326,6 +386,47 @@ 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).
 
+### LibreChat on the same host (no public URL)
+
+To run LibreChat and this server on one machine over plain HTTP, with no public domain or TLS, run this server as a sidecar that shares the LibreChat api container's network namespace. That makes `http://localhost:3001` the same address for both your browser and LibreChat's backend, and Google allows `http://localhost` as the one non-HTTPS OAuth redirect, so sign-in works without a certificate.
+
+Add to LibreChat's `docker-compose.override.yml`:
+
+```yaml
+services:
+  api:
+    ports:
+      - "3001:3001"                 # expose the sidecar to your browser
+  google-ads-mcp:
+    image: node:24-bookworm-slim
+    command: ["npx", "-y", "@aligulzar729/google-ads-mcp", "--http"]
+    network_mode: "service:api"     # share the api netns: one localhost for browser and backend
+    depends_on:
+      - api
+    environment:
+      PORT: "3001"
+      PUBLIC_BASE_URL: "http://localhost:3001"
+      ALLOWED_REDIRECT_ORIGINS: "http://localhost:3080"   # your LibreChat origin
+      GOOGLE_ADS_DEVELOPER_TOKEN: ${GOOGLE_ADS_DEVELOPER_TOKEN}
+      GOOGLE_OAUTH_CLIENT_ID: ${GOOGLE_OAUTH_CLIENT_ID}
+      GOOGLE_OAUTH_CLIENT_SECRET: ${GOOGLE_OAUTH_CLIENT_SECRET}
+      TOKEN_ENC_KEY: ${TOKEN_ENC_KEY}
+      AUDIT_DB_PATH: /app/data/audit.db
+    volumes:
+      - ads_data:/app/data
+volumes:
+  ads_data:
+```
+
+Then:
+
+- Point the LibreChat entry at `url: "http://localhost:3001/mcp"` with `requiresOAuth: true` (see [LibreChat](#add-it-to-your-ai-harness) above), and keep `localhost` in `mcpSettings.allowedDomains`.
+- Register `http://localhost:3001/auth/callback` as a redirect URI on the Google OAuth client.
+- Sign in from Chrome or Firefox: the consent cookie is `Secure`, and those treat `localhost` as a secure context. Safari may refuse it.
+- The sidecar shares the api container's network, so recreate both together after changes: `docker compose up -d --force-recreate api google-ads-mcp`.
+
+Publish the OAuth app to In Production so per-user tokens do not expire after 7 days.
+
 ## Tools
 
 Seven tools, each takes an `action`:
@@ -342,6 +443,14 @@ Seven tools, each takes an `action`:
 
 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.
 
+## Coverage
+
+| | |
+|---|---|
+| Google Ads API version | v24.1 (via [`google-ads-api`](https://github.com/Opteo/google-ads-api), Opteo) |
+| Coverage model | Curated actions for the common workflows, plus raw GAQL over every non-sensitive report resource. Not a 1:1 mapping of the ~100 API services. |
+| Write safety | Preview-first, yes/ok confirmation, PAUSED creates, durable audit log (see [Money and safety](#money-and-safety)). |
+
 ## Big reports and pagination
 
 Reports are bounded per response and paged without hitting Google again:
@@ -365,16 +474,20 @@ Reporting is read-only and retried, so it's reliable for cron and scheduled jobs
 | 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. |
+| `PERMISSION_DENIED` / "set login-customer-id" | `GOOGLE_ADS_LOGIN_CUSTOMER_ID` is only for reaching a client *through a manager*. For an account you access directly (it shows as `[client]` in `account list`), leave it empty. Setting a manager you do not reach that client through, or setting one at all when none is needed, causes this error. If it is still denied, the login genuinely lacks access to that customer id. |
+| `unauthorized_client` on token exchange | The refresh token was minted by a different OAuth client than `GOOGLE_OAUTH_CLIENT_ID`. Re-mint it with that exact client (in the OAuth Playground, check "Use your own OAuth credentials" first). |
 | 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. |
+| OAuth works but LibreChat never connects | Set `requiresOAuth: true` and `startup: false` on the MCP entry, add the host to `allowedDomains`, and point `url` at the public `/mcp` path. |
+| LibreChat logs `OAuth not supported in unauthenticated discovery` or repeated `Reinspection failed ... timeout` | Missing `requiresOAuth: true`. LibreChat is probing the server without auth to list tools, which always fails on an OAuth server. The flag silences the probe and shows the sign-in prompt directly. |
+| Stale connection after changing the server URL under the same name | LibreChat caches OAuth tokens per server name. Reconnect, or clear its cached tokens for that server, so it registers fresh against the new backend. |
+| Google returns `redirect_uri_mismatch` mid sign-in | `PUBLIC_BASE_URL/auth/callback` is not registered on the OAuth client. For localhost that is `http://localhost:3001/auth/callback`. |
 
 ## 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.
+- 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 v24.1. 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.
 
@@ -382,6 +495,10 @@ Reporting is read-only and retried, so it's reliable for cron and scheduled jobs
 
 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.
 
+## Disclaimer
+
+This is an unofficial Google Ads API integration. It is not affiliated with, endorsed by, or supported by Google. "Google Ads" is a trademark of Google LLC. You are responsible for your account and any spend; use it within Google's API Terms of Service.
+
 ## License
 
 MIT

package/dist/index.js

@@ -1995,7 +1995,7 @@ var metadataHandler = {
 // src/tools/orchestrators/report.ts
 var reportTool = defineOrchestrator({
   name: "google_ads_report",
-  purpose: "Read Google Ads performance. Prefer a curated action: campaign_performance for any channel, impression_share for Search visibility (the Average Position replacement), or asset_group for Performance Max. For anything else, daily or weekly trends, keyword or search-term views, custom field combinations, use gaql after calling metadata first.",
+  purpose: 'Read Google Ads performance. Prefer a curated action: campaign_performance for any channel, impression_share for Search visibility (the Average Position replacement), or asset_group for Performance Max. For anything else, daily or weekly trends, keyword or search-term views, custom field combinations, use gaql after calling metadata first. Resource hints for less obvious asks: "cart / basket value / cross-sell sales" -> cart_data_sales_view ; "iOS vs Android breakdown" -> add the segment segments.mobile_device_platform. Always call metadata on a resource before querying it to get its exact field names.',
   limitations: "Read-only. ROAS is computed as conversion value divided by cost. Average Position does not exist; use action impression_share instead. impression_share only applies to Search campaigns; asset_group only applies to Performance Max. Curated reports already format values, but in raw gaql results, money fields are in micros (divide by 1,000,000) and rates (metrics.ctr, conversion rate, impression share) are ratios from 0 to 1. For gaql, do not guess field names: call metadata first to get the exact selectable, filterable, and sortable fields plus compatible metrics and segments, then use those names verbatim.",
   examples: [
     '{"action":"campaign_performance","date_range":"LAST_30_DAYS"}',
@@ -2063,7 +2063,7 @@ function langId(s) {
 // src/tools/handlers/campaign/create.ts
 var schema10 = z13.object({
   name: z13.string().min(1).max(255),
-  channel_type: z13.enum(["SEARCH", "PERFORMANCE_MAX", "DISPLAY", "DEMAND_GEN", "VIDEO", "APP", "SHOPPING"]),
+  channel_type: z13.enum(["SEARCH", "PERFORMANCE_MAX", "DISPLAY", "DEMAND_GEN", "APP", "SHOPPING"]),
   daily_budget: z13.number().positive().describe("Daily amount in account currency (e.g. 50 = 50.00/day)"),
   bidding: z13.enum(BIDDING).default("MAXIMIZE_CONVERSIONS"),
   target_cpa: z13.number().positive().optional().describe("Target CPA in account currency (TARGET_CPA / MAXIMIZE_CONVERSIONS)"),
@@ -2077,7 +2077,7 @@ var schema10 = z13.object({
 });
 var createHandler = {
   action: "create",
-  summary: "Create a campaign plus its daily budget, atomically. channel_type: SEARCH, DISPLAY, DEMAND_GEN, VIDEO, PERFORMANCE_MAX, APP (needs app_id + app_store, TARGET_CPA bidding), or SHOPPING (needs merchant_id from a linked Merchant Center). Created PAUSED. Preview first (omit confirmed). Then ask the user to type yes or ok in chat; only after that re-call with confirmed:true and user_confirmation yes|ok.",
+  summary: "Create a campaign plus its daily budget, atomically. channel_type: SEARCH, DISPLAY, DEMAND_GEN (use this for YouTube; Google no longer lets the API create Video campaigns), PERFORMANCE_MAX, APP (needs app_id + app_store, TARGET_CPA bidding), or SHOPPING (needs merchant_id from a linked Merchant Center). Created PAUSED. Preview first (omit confirmed). Then ask the user to type yes or ok in chat; only after that re-call with confirmed:true and user_confirmation yes|ok.",
   readOnly: false,
   category: "mutate",
   schema: schema10,
@@ -2102,9 +2102,6 @@ Ask the user, then call create again with brand_guidelines_enabled set to true o
     if (params.channel_type === "DEMAND_GEN" && params.bidding === "MANUAL_CPC") {
       throw new Error("Demand Gen requires automated bidding (not MANUAL_CPC): use MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CONVERSION_VALUE, or TARGET_ROAS.");
     }
-    if (params.channel_type === "VIDEO" && params.bidding !== "MAXIMIZE_CONVERSIONS" && params.bidding !== "TARGET_CPA") {
-      throw new Error("A Video Action campaign requires automated bidding (MAXIMIZE_CONVERSIONS or TARGET_CPA), not MANUAL_CPC.");
-    }
     if (params.channel_type === "APP") {
       if (!params.app_id) throw new Error("app_id is required for an App campaign (the Android package name or numeric iOS App Store id).");
       if (!params.app_store) throw new Error("app_store is required for an App campaign (GOOGLE_APP_STORE or APPLE_APP_STORE).");
@@ -2119,7 +2116,6 @@ Ask the user, then call create again with brand_guidelines_enabled set to true o
       SEARCH: enums3.AdvertisingChannelType.SEARCH,
       DISPLAY: enums3.AdvertisingChannelType.DISPLAY,
       DEMAND_GEN: enums3.AdvertisingChannelType.DEMAND_GEN,
-      VIDEO: enums3.AdvertisingChannelType.VIDEO,
       PERFORMANCE_MAX: enums3.AdvertisingChannelType.PERFORMANCE_MAX,
       SHOPPING: enums3.AdvertisingChannelType.SHOPPING,
       APP: enums3.AdvertisingChannelType.MULTI_CHANNEL
@@ -2139,8 +2135,6 @@ Ask the user, then call create again with brand_guidelines_enabled set to true o
       campaign.network_settings = { target_google_search: true, target_search_network: true };
     } else if (params.channel_type === "DISPLAY") {
       campaign.network_settings = { target_content_network: true };
-    } else if (params.channel_type === "VIDEO") {
-      campaign.advertising_channel_sub_type = enums3.AdvertisingChannelSubType.VIDEO_ACTION;
     } else if (params.channel_type === "APP") {
       campaign.advertising_channel_sub_type = enums3.AdvertisingChannelSubType.APP_CAMPAIGN;
       campaign.app_campaign_setting = {
@@ -2183,7 +2177,6 @@ Ask the user, then call create again with brand_guidelines_enabled set to true o
       PERFORMANCE_MAX: "\nNext: add an asset group before enabling, a P-MAX campaign needs assets to serve.",
       DISPLAY: "\nNext: add an ad group, then a responsive display ad (add_ad ad_type RESPONSIVE_DISPLAY_AD) or an HTML5 ad, then enable the campaign.",
       DEMAND_GEN: "\nNext: add an ad group, then a Demand Gen ad (add_ad ad_type DEMAND_GEN_MULTI_ASSET), then enable the campaign.",
-      VIDEO: "\nNext: add an ad group, then a responsive video ad (add_ad ad_type VIDEO_RESPONSIVE with a YouTube video), then enable the campaign.",
       APP: "\nNext: App campaigns auto-create an ad group, find it with ad_group list_ads (or a report), add an app ad (add_ad ad_type APP), then enable the campaign.",
       SHOPPING: "\nNext: add an ad group, then a product ad (add_ad ad_type SHOPPING_PRODUCT). Products serve from the linked Merchant Center feed, make sure Merchant Center is linked.",
       SEARCH: "\nNext: add an ad group and a responsive search ad, then enable the campaign."
@@ -2481,7 +2474,7 @@ var targetingHandler = {
 var campaignTool = defineOrchestrator({
   name: "google_ads_campaign",
   purpose: "Create and manage campaigns. create builds a new one for Search, Display, Demand Gen, App, Shopping, or Performance Max (for YouTube, use DEMAND_GEN, not VIDEO). update renames it or changes its dates and network settings. status pauses or resumes it. budget sets the daily budget. bidding sets the bidding strategy. targeting sets location, language, and schedule.",
-  limitations: "Every write previews first; then the user must type yes or ok in chat before confirmed:true + user_confirmation. New campaigns are created PAUSED. All edits here are in-place updates, not delete-and-recreate. Use the right action: update for name, dates, and networks; status for pause or resume; budget for the daily budget; bidding for the strategy; targeting for locations, languages, and schedule. Get campaign_id from report. Performance Max, Demand Gen, and Video all require automated bidding. App needs app_id, app_store, and TARGET_CPA bidding. Shopping needs a merchant_id from a linked Merchant Center account. VIDEO campaigns can no longer be created through the API (Google sunset Video Action campaigns for Demand Gen), so use DEMAND_GEN for YouTube instead. Location and language are numeric ids, so resolve names with google_ads_lookup first.",
+  limitations: "Every write previews first; then the user must type yes or ok in chat before confirmed:true + user_confirmation. New campaigns are created PAUSED. All edits here are in-place updates, not delete-and-recreate. Use the right action: update for name, dates, and networks; status for pause or resume; budget for the daily budget; bidding for the strategy; targeting for locations, languages, and schedule. Get campaign_id from report. Performance Max and Demand Gen require automated bidding. App needs app_id, app_store, and TARGET_CPA bidding. Shopping needs a merchant_id from a linked Merchant Center account. VIDEO campaigns can no longer be created through the API (Google sunset Video Action campaigns for Demand Gen), so use DEMAND_GEN for YouTube instead. Location and language are numeric ids, so resolve names with google_ads_lookup first.",
   examples: [
     '{"action":"create","name":"Brand - Search","channel_type":"SEARCH","daily_budget":50,"bidding":"MAXIMIZE_CONVERSIONS"}',
     '{"action":"create","name":"App - Installs","channel_type":"APP","daily_budget":50,"bidding":"TARGET_CPA","target_cpa":3,"app_id":"com.example.app","app_store":"GOOGLE_APP_STORE"}',
@@ -4260,7 +4253,7 @@ function registerOAuthRoutes(app, broker) {
 
 // src/app.ts
 async function startHttp(config, deps) {
-  const { ads, audit, logger, store } = deps;
+  const { ads, audit, logger, store, db } = deps;
   const pageCache = new PageCache();
   const oauthLimiter = new RateLimiter(60, 6e4);
   const mcpLimiter = new RateLimiter(120, 6e4);
@@ -4291,6 +4284,68 @@ async function startHttp(config, deps) {
     return remote || "unknown";
   };
   app.get("/healthz", (c) => c.json({ status: "ok", mode: "http" }));
+  const SYNC_TABLES = ["oauth_clients", "oauth_sessions", "oauth_tokens", "audit"];
+  const syncKey = process.env.INTERNAL_SYNC_KEY;
+  const syncAuth = (c) => {
+    if (!syncKey) return false;
+    const auth = c.req.header("authorization") ?? "";
+    const token = auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
+    return token === syncKey;
+  };
+  app.get("/internal/sync", (c) => {
+    if (!syncAuth(c)) return c.json({ error: "unauthorized" }, 401);
+    if (c.req.query("rev") !== void 0) {
+      const r = db.prepare(
+        `SELECT
+           (SELECT COUNT(*) FROM oauth_clients)                     AS c,
+           (SELECT COUNT(*) FROM oauth_sessions)                    AS s,
+           (SELECT COALESCE(MAX(last_used_ts), 0) FROM oauth_sessions) AS slu,
+           (SELECT COUNT(*) FROM oauth_tokens)                      AS t,
+           (SELECT COALESCE(MAX(id), 0) FROM audit)                 AS a`
+      ).get();
+      return c.json({ rev: `${r.c}:${r.s}:${r.slu}:${r.t}:${r.a}`, maxAuditId: r.a });
+    }
+    const auditSince = Number(c.req.query("auditSince") ?? 0) || 0;
+    const maxAuditId = db.prepare("SELECT COALESCE(MAX(id), 0) AS a FROM audit").get().a;
+    const tables = {
+      oauth_clients: db.prepare("SELECT * FROM oauth_clients").all(),
+      oauth_sessions: db.prepare("SELECT * FROM oauth_sessions").all(),
+      oauth_tokens: db.prepare("SELECT * FROM oauth_tokens").all(),
+      audit: db.prepare("SELECT * FROM audit WHERE id > ?").all(auditSince)
+    };
+    return c.json({ tables, maxAuditId });
+  });
+  app.post("/internal/sync", async (c) => {
+    if (!syncAuth(c)) return c.json({ error: "unauthorized" }, 401);
+    const body = await c.req.json().catch(() => null);
+    if (!body?.tables || typeof body.tables !== "object") {
+      return c.json({ error: "expected { tables: { ... } }" }, 400);
+    }
+    db.exec("BEGIN");
+    try {
+      for (const t of SYNC_TABLES) {
+        db.prepare(`DELETE FROM ${t}`).run();
+        const rows = body.tables[t] ?? [];
+        for (const row of rows) {
+          const cols = Object.keys(row);
+          const placeholders = cols.map(() => "?").join(", ");
+          db.prepare(`INSERT INTO ${t} (${cols.join(", ")}) VALUES (${placeholders})`).run(...cols.map((k) => row[k]));
+        }
+      }
+      db.exec("COMMIT");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      logger.error("sync", "internal sync import failed", { error: e instanceof Error ? e.message : String(e) });
+      return c.json({ error: "sync failed" }, 500);
+    }
+    logger.info("sync", "internal sync import complete", {
+      clients: body.tables.oauth_clients?.length ?? 0,
+      sessions: body.tables.oauth_sessions?.length ?? 0,
+      tokens: body.tables.oauth_tokens?.length ?? 0,
+      audit: body.tables.audit?.length ?? 0
+    });
+    return c.json({ ok: true });
+  });
   app.use("/register", async (c, next) => {
     if (!oauthLimiter.allow(`reg:${clientIp(c)}`)) return c.json({ error: "rate_limit", message: "Too many registration requests. Retry later." }, 429);
     return next();
@@ -4476,7 +4531,7 @@ async function main() {
   const db = openDb(config.auditDbPath);
   const audit = new Audit(db, logger);
   const store = new OAuthStore(db, loadEncKey(config.tokenEncKey));
-  const running = await startHttp(config, { ads, audit, logger, store });
+  const running = await startHttp(config, { ads, audit, logger, store, db });
   const shutdown = (sig) => {
     logger.info("main", `received ${sig}, shutting down`);
     const hard = setTimeout(() => process.exit(1), 8e3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aligulzar729/google-ads-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Manage Google Ads from Claude, Codex, LibreChat, or any MCP client. Natural-language reporting plus guarded campaign, keyword, and Performance Max operations.",
   "type": "module",
   "bin": {
@@ -51,22 +51,22 @@
     "access": "public"
   },
   "dependencies": {
-    "@hono/node-server": "^1.19.12",
+    "@hono/node-server": "^2.0.8",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "google-ads-api": "^23.0.0",
+    "google-ads-api": "^24.1.0",
     "google-auth-library": "^9.15.0",
     "hono": "^4.12.28",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^22.10.0",
+    "@types/node": "^26.1.1",
     "eslint": "^10.6.0",
     "globals": "^17.7.0",
     "tsup": "^8.3.5",
     "tsx": "^4.23.0",
-    "typescript": "^5.7.2",
+    "typescript": "~6.0.3",
     "typescript-eslint": "^8.63.0",
-    "vitest": "^2.1.8"
+    "vitest": "^4.1.10"
   }
 }