mcp-google-ads 1.0.16 → 1.1.0

package/dist/auth-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function run(argv?: string[]): Promise<void>;

package/dist/auth-cli.js

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+import { GoogleAdsApi } from "google-ads-api";
+import http from "http";
+import promptsImport from "prompts";
+import { URL } from "url";
+import { writeStoredCredentials, credentialsFilePath, CREDENTIALS_FILE_VERSION } from "./credentials.js";
+import {
+  EMBEDDED_CLIENT_ID,
+  EMBEDDED_CLIENT_SECRET,
+  EMBEDDED_DEVELOPER_TOKEN
+} from "./embedded-secrets.js";
+import { classifyError, GoogleAdsAuthError } from "./errors.js";
+import { findFreeLoopbackPort, openBrowser } from "./platform.js";
+import { logger, withResilience } from "./resilience.js";
+const prompts = promptsImport.default ?? promptsImport;
+const OAUTH_SCOPE = "https://www.googleapis.com/auth/adwords";
+const OAUTH_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const OAUTH_TOKEN_URL = "https://oauth2.googleapis.com/token";
+function parseArgs(argv) {
+  const args = { help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") args.help = true;
+    else if (a === "--customer-id" && argv[i + 1]) {
+      args.customerId = argv[++i].replace(/-/g, "");
+    }
+  }
+  return args;
+}
+function printHelp() {
+  process.stdout.write(
+    [
+      "mcp-google-ads-auth  \u2014  authorize Claude to access your Google Ads account",
+      "",
+      "Usage:",
+      "  npx mcp-google-ads-auth",
+      "  npx mcp-google-ads-auth --customer-id 374-196-1572",
+      "",
+      "Options:",
+      "  --customer-id <id>   Skip the account picker and use this customer ID directly",
+      "  -h, --help           Show this help",
+      "",
+      `Credentials are written to: ${credentialsFilePath}`,
+      ""
+    ].join("\n")
+  );
+}
+function buildAuthUrl(clientId, redirectUri, state) {
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: OAUTH_SCOPE,
+    access_type: "offline",
+    prompt: "consent",
+    state
+  });
+  return `${OAUTH_AUTH_URL}?${params.toString()}`;
+}
+async function waitForAuthorizationCode(port, expectedState, authUrl) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+    const server = http.createServer((req, res) => {
+      if (!req.url) {
+        res.writeHead(404).end();
+        return;
+      }
+      const parsed = new URL(req.url, `http://127.0.0.1:${port}`);
+      const code = parsed.searchParams.get("code");
+      const state = parsed.searchParams.get("state");
+      const error = parsed.searchParams.get("error");
+      if (error) {
+        const body2 = renderAuthCompletePage(
+          "Authorization was denied",
+          `Google returned: ${escapeHtml(error)}. You can close this tab and re-run the command.`
+        );
+        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(body2);
+        finish(() => {
+          server.close();
+          reject(new GoogleAdsAuthError(`OAuth denied: ${error}`));
+        });
+        return;
+      }
+      if (!code) {
+        res.writeHead(204).end();
+        return;
+      }
+      if (state !== expectedState) {
+        const body2 = renderAuthCompletePage(
+          "Security check failed",
+          "The state parameter did not match. This tab may have been tampered with. Please re-run the command."
+        );
+        res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+        res.end(body2);
+        finish(() => {
+          server.close();
+          reject(new GoogleAdsAuthError("OAuth state mismatch \u2014 possible CSRF"));
+        });
+        return;
+      }
+      const body = renderAuthCompletePage(
+        "Signed in successfully",
+        "You can close this tab and return to the terminal."
+      );
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(body);
+      finish(() => {
+        setTimeout(() => server.close(), 200);
+        resolve({ code, state });
+      });
+    });
+    server.on("error", (err) => {
+      finish(() => reject(new Error(`Loopback server failed: ${err.message}`)));
+    });
+    server.listen(port, "127.0.0.1", () => {
+      process.stderr.write(`
+Opening your browser to sign in with Google...
+`);
+      process.stderr.write(`If it doesn't open automatically, visit:
+  ${authUrl}
+
+`);
+      openBrowser(authUrl).catch((err) => {
+        logger.warn({ err: err.message }, "openBrowser failed \u2014 user can paste URL manually");
+      });
+    });
+    setTimeout(() => {
+      finish(() => {
+        server.close();
+        reject(new Error("Timed out waiting for OAuth callback (5 minutes). Re-run the command."));
+      });
+    }, 5 * 60 * 1e3);
+  });
+}
+function renderAuthCompletePage(title, body) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>${escapeHtml(title)}</title>
+  <style>
+    body { font: 15px -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+           max-width: 480px; margin: 80px auto; padding: 0 24px; color: #222; }
+    h1 { font-size: 22px; margin-bottom: 12px; }
+    p { line-height: 1.5; }
+  </style>
+</head>
+<body>
+  <h1>${escapeHtml(title)}</h1>
+  <p>${escapeHtml(body)}</p>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+  return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+async function exchangeCodeForTokens(code, clientId, clientSecret, redirectUri) {
+  return withResilience(async () => {
+    const body = new URLSearchParams({
+      code,
+      client_id: clientId,
+      client_secret: clientSecret,
+      redirect_uri: redirectUri,
+      grant_type: "authorization_code"
+    });
+    const res = await fetch(OAUTH_TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString()
+    });
+    const json = await res.json();
+    if (!res.ok || json.error) {
+      const err = new Error(
+        `Token exchange failed: ${json.error_description || json.error || res.statusText}`
+      );
+      err.status = res.status;
+      err.code = res.status;
+      throw err;
+    }
+    return json;
+  }, "oauth.exchangeCode");
+}
+async function enumerateAccounts(api, refreshToken) {
+  const listed = await withResilience(
+    () => api.listAccessibleCustomers(refreshToken),
+    "auth.listAccessibleCustomers"
+  );
+  const topLevelIds = (listed.resource_names || []).map(
+    (rn) => rn.replace("customers/", "")
+  );
+  if (topLevelIds.length === 0) {
+    throw new GoogleAdsAuthError(
+      "No Google Ads accounts accessible to this Google login. Make sure you signed in with an account that has access to at least one Google Ads account."
+    );
+  }
+  const accounts = [];
+  for (const id of topLevelIds) {
+    try {
+      const customer = api.Customer({ customer_id: id, refresh_token: refreshToken });
+      const rows = await withResilience(
+        () => customer.query("SELECT customer.id, customer.descriptive_name, customer.manager FROM customer LIMIT 1"),
+        `auth.fetchCustomer[${id}]`
+      );
+      const row = rows[0]?.customer;
+      const name = row?.descriptive_name || `(unnamed ${id})`;
+      const isManager = Boolean(row?.manager);
+      accounts.push({ id, name, isManager });
+      if (isManager) {
+        const mccCustomer = api.Customer({
+          customer_id: id,
+          refresh_token: refreshToken,
+          login_customer_id: id
+        });
+        try {
+          const children = await withResilience(
+            () => mccCustomer.query(
+              "SELECT customer_client.id, customer_client.descriptive_name, customer_client.manager FROM customer_client WHERE customer_client.manager = FALSE AND customer_client.status = 'ENABLED'"
+            ),
+            `auth.enumerateChildren[${id}]`
+          );
+          for (const childRow of children) {
+            const cc = childRow.customer_client;
+            if (!cc?.id) continue;
+            const childId = String(cc.id);
+            if (childId === id) continue;
+            accounts.push({
+              id: childId,
+              name: cc.descriptive_name || `(unnamed ${childId})`,
+              isManager: false,
+              parentMccId: id,
+              parentMccName: name
+            });
+          }
+        } catch (err) {
+          logger.warn(
+            { err: err.message, mccId: id },
+            "Failed to enumerate MCC children \u2014 MCC will still appear in picker"
+          );
+        }
+      }
+    } catch (err) {
+      const classified = classifyError(err);
+      if (classified instanceof GoogleAdsAuthError) throw classified;
+      logger.warn({ err: classified.message, customerId: id }, "Failed to fetch account info \u2014 skipping");
+    }
+  }
+  return accounts;
+}
+async function pickAccount(accounts, presetCustomerId) {
+  if (presetCustomerId) {
+    const match = accounts.find((a) => a.id === presetCustomerId);
+    if (!match) {
+      throw new Error(
+        `--customer-id ${presetCustomerId} was not found among ${accounts.length} accessible account(s). Remove the flag to pick interactively.`
+      );
+    }
+    return match;
+  }
+  if (accounts.length === 1) {
+    process.stderr.write(
+      `
+Only one account accessible: ${accounts[0].name} (${accounts[0].id}). Auto-selecting.
+`
+    );
+    return accounts[0];
+  }
+  const sorted = [...accounts].sort((a, b) => {
+    const aKey = a.parentMccId ? `${a.parentMccId}:1:${a.name}` : `${a.id}:0:${a.name}`;
+    const bKey = b.parentMccId ? `${b.parentMccId}:1:${b.name}` : `${b.id}:0:${b.name}`;
+    return aKey.localeCompare(bKey);
+  });
+  const choices = sorted.map((acct) => {
+    const prefix = acct.parentMccId ? "    \u21B3 " : acct.isManager ? "\u{1F4C1} " : "\u2022 ";
+    const mccSuffix = acct.parentMccId ? "" : acct.isManager ? " (MCC)" : "";
+    return {
+      title: `${prefix}${acct.name} \u2014 ${acct.id}${mccSuffix}`,
+      value: acct,
+      disabled: acct.isManager && accounts.some((a) => a.parentMccId === acct.id) ? false : false
+    };
+  });
+  const response = await prompts(
+    {
+      type: "select",
+      name: "account",
+      message: "Which Google Ads account should Claude use?",
+      choices,
+      initial: 0
+    },
+    {
+      onCancel: () => {
+        throw new Error("Cancelled by user");
+      }
+    }
+  );
+  if (!response.account) {
+    throw new Error("No account selected");
+  }
+  return response.account;
+}
+async function run(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    printHelp();
+    return;
+  }
+  const clientId = process.env.GOOGLE_ADS_CLIENT_ID?.trim() || EMBEDDED_CLIENT_ID;
+  const clientSecret = process.env.GOOGLE_ADS_CLIENT_SECRET?.trim() || EMBEDDED_CLIENT_SECRET;
+  const developerToken = process.env.GOOGLE_ADS_DEVELOPER_TOKEN?.trim() || EMBEDDED_DEVELOPER_TOKEN;
+  if (!clientId || !clientSecret || !developerToken) {
+    process.stderr.write(
+      "This build of mcp-google-ads was published without embedded OAuth credentials.\nSet GOOGLE_ADS_CLIENT_ID, GOOGLE_ADS_CLIENT_SECRET, and GOOGLE_ADS_DEVELOPER_TOKEN\nin your environment before running this command.\n"
+    );
+    process.exit(2);
+  }
+  const port = await findFreeLoopbackPort();
+  const redirectUri = `http://127.0.0.1:${port}`;
+  const state = randomState();
+  const authUrl = buildAuthUrl(clientId, redirectUri, state);
+  process.stderr.write("\n=== mcp-google-ads authentication ===\n");
+  const { code } = await waitForAuthorizationCode(port, state, authUrl);
+  process.stderr.write("Authorization code received. Exchanging for tokens...\n");
+  const tokens = await exchangeCodeForTokens(code, clientId, clientSecret, redirectUri);
+  if (!tokens.refresh_token) {
+    throw new GoogleAdsAuthError(
+      "Google did not return a refresh token. This can happen if you previously granted consent to this app \u2014 revoke access at https://myaccount.google.com/permissions and try again."
+    );
+  }
+  process.stderr.write("Tokens received. Fetching accessible Google Ads accounts...\n");
+  const api = new GoogleAdsApi({
+    client_id: clientId,
+    client_secret: clientSecret,
+    developer_token: developerToken
+  });
+  const accounts = await enumerateAccounts(api, tokens.refresh_token);
+  const chosen = await pickAccount(accounts, args.customerId);
+  const stored = {
+    version: CREDENTIALS_FILE_VERSION,
+    refresh_token: tokens.refresh_token,
+    customer_id: chosen.id,
+    customer_name: chosen.name,
+    mcc_customer_id: chosen.parentMccId ?? null,
+    obtained_at: (/* @__PURE__ */ new Date()).toISOString(),
+    scopes: [OAUTH_SCOPE]
+  };
+  writeStoredCredentials(stored);
+  process.stderr.write(
+    [
+      "",
+      "\u2705 Done.",
+      "",
+      `  Account:    ${chosen.name} (${chosen.id})`,
+      chosen.parentMccId ? `  Via MCC:    ${chosen.parentMccName} (${chosen.parentMccId})` : `  (Direct access \u2014 no MCC)`,
+      `  Saved to:   ${credentialsFilePath}`,
+      "",
+      "Next step: fully quit Claude Desktop (Cmd+Q / File > Exit) and reopen it.",
+      'Then try: "List campaigns in Google Ads"',
+      ""
+    ].join("\n")
+  );
+}
+function randomState() {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+const isMain = import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/auth-cli.js") || process.argv[1]?.endsWith("\\auth-cli.js");
+if (isMain) {
+  run().catch((err) => {
+    const classified = classifyError(err);
+    process.stderr.write(`
+\u274C ${classified.message}
+`);
+    process.exit(1);
+  });
+}
+export {
+  run
+};
+//# sourceMappingURL=auth-cli.js.map

package/dist/build-info.json

@@ -1 +1,5 @@
-{"sha":"9b25077","builtAt":"2026-04-09T23:18:47.469Z"}
+{
+  "sha": "fceb9f2",
+  "builtAt": "2026-04-13T00:50:57.276Z",
+  "embeddedSecrets": true
+}

package/dist/credentials.d.ts

@@ -0,0 +1,38 @@
+export declare const CREDENTIALS_FILE_VERSION = 1;
+export interface StoredCredentials {
+    version: number;
+    refresh_token: string;
+    customer_id: string;
+    customer_name?: string;
+    mcc_customer_id?: string | null;
+    obtained_at: string;
+    scopes: string[];
+}
+export interface ResolvedCredentials {
+    client_id: string;
+    client_secret: string;
+    developer_token: string;
+    refresh_token: string;
+    customer_id: string;
+    mcc_customer_id: string;
+    source: "env" | "file" | "mixed";
+}
+export declare function readStoredCredentials(filePath?: string): StoredCredentials | null;
+export declare function writeStoredCredentials(creds: StoredCredentials, filePath?: string): void;
+/**
+ * Resolve all credentials needed to make Google Ads API calls.
+ *
+ * Throws a descriptive Error if any required value is missing after
+ * walking the entire priority chain. The error message points users to
+ * the correct action (run the auth helper vs. set env vars).
+ *
+ * The optional `credsFilePath` parameter exists so tests can point at a
+ * tmpdir instead of reading the real ~/Library credentials file, and so
+ * the MCP server's multi-client mode can read a different location.
+ */
+export declare function resolveCredentials(credsFilePath?: string): ResolvedCredentials;
+export declare function validateResolvedCredentials(creds: ResolvedCredentials): {
+    valid: boolean;
+    issues: string[];
+};
+export { configDir, credentialsFilePath } from "./platform.js";

package/dist/credentials.js

@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync } from "fs";
+import path from "path";
+import {
+  EMBEDDED_CLIENT_ID,
+  EMBEDDED_CLIENT_SECRET,
+  EMBEDDED_DEVELOPER_TOKEN
+} from "./embedded-secrets.js";
+import { credentialsFilePath } from "./platform.js";
+import { logger } from "./resilience.js";
+const CREDENTIALS_FILE_VERSION = 1;
+const envTrimmed = (key) => (process.env[key] || "").trim().replace(/^["']|["']$/g, "");
+function readStoredCredentials(filePath = credentialsFilePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    const raw = readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== CREDENTIALS_FILE_VERSION) {
+      logger.warn(
+        { path: filePath, version: parsed.version, expected: CREDENTIALS_FILE_VERSION },
+        "Credentials file version mismatch \u2014 ignoring"
+      );
+      return null;
+    }
+    return parsed;
+  } catch (err) {
+    logger.warn({ err, path: filePath }, "Failed to parse credentials file \u2014 ignoring");
+    return null;
+  }
+}
+function writeStoredCredentials(creds, filePath = credentialsFilePath) {
+  const dir = path.dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, JSON.stringify(creds, null, 2), { encoding: "utf-8" });
+  try {
+    chmodSync(filePath, 384);
+  } catch {
+  }
+}
+function resolveCredentials(credsFilePath = credentialsFilePath) {
+  const client_id = envTrimmed("GOOGLE_ADS_CLIENT_ID") || EMBEDDED_CLIENT_ID;
+  const client_secret = envTrimmed("GOOGLE_ADS_CLIENT_SECRET") || EMBEDDED_CLIENT_SECRET;
+  const developer_token = envTrimmed("GOOGLE_ADS_DEVELOPER_TOKEN") || EMBEDDED_DEVELOPER_TOKEN;
+  const stored = readStoredCredentials(credsFilePath);
+  const envRefresh = envTrimmed("GOOGLE_ADS_REFRESH_TOKEN");
+  const envCustomer = envTrimmed("GOOGLE_ADS_CUSTOMER_ID");
+  const envMcc = envTrimmed("GOOGLE_ADS_MCC_CUSTOMER_ID");
+  const refresh_token = envRefresh || stored?.refresh_token || "";
+  const customer_id = envCustomer || stored?.customer_id || "";
+  const mcc_customer_id = envMcc || stored?.mcc_customer_id || "";
+  const source = envRefresh && stored ? "mixed" : envRefresh ? "env" : stored ? "file" : "env";
+  const missing = [];
+  if (!client_id) missing.push("client_id");
+  if (!client_secret) missing.push("client_secret");
+  if (!developer_token) missing.push("developer_token");
+  if (!refresh_token) missing.push("refresh_token");
+  if (!customer_id) missing.push("customer_id");
+  if (missing.length > 0) {
+    throw new Error(buildMissingCredentialsMessage(missing, Boolean(stored)));
+  }
+  return {
+    client_id,
+    client_secret,
+    developer_token,
+    refresh_token,
+    customer_id,
+    mcc_customer_id,
+    source
+  };
+}
+function buildMissingCredentialsMessage(missing, hasFile) {
+  const runAuth = "npx mcp-google-ads-auth";
+  const lines = [
+    `Missing Google Ads credentials: ${missing.join(", ")}.`,
+    ``,
+    `To get started, run:`,
+    `    ${runAuth}`,
+    ``,
+    `This will open your browser, walk you through Google sign-in, let you pick which`,
+    `Google Ads account to use, and save the result to:`,
+    `    ${credentialsFilePath}`
+  ];
+  if (hasFile) {
+    lines.push(
+      ``,
+      `A credentials file exists at ${credentialsFilePath} but is missing required fields.`,
+      `Re-run the auth helper to refresh it.`
+    );
+  }
+  lines.push(
+    ``,
+    `Advanced: you can bypass the auth helper by setting these env vars in your`,
+    `Claude Desktop config: GOOGLE_ADS_REFRESH_TOKEN, GOOGLE_ADS_CUSTOMER_ID.`
+  );
+  return lines.join("\n");
+}
+function validateResolvedCredentials(creds) {
+  const issues = [];
+  const check = (name, val, minLen = 10) => {
+    if (val.length < minLen) issues.push(`${name} too short (expected >=${minLen} chars, got ${val.length})`);
+  };
+  check("client_id", creds.client_id);
+  check("client_secret", creds.client_secret);
+  check("developer_token", creds.developer_token);
+  check("refresh_token", creds.refresh_token);
+  const custDigits = creds.customer_id.replace(/-/g, "");
+  if (!/^\d{10}$/.test(custDigits)) {
+    issues.push(`customer_id must be 10 digits (got "${creds.customer_id}")`);
+  }
+  return { valid: issues.length === 0, issues };
+}
+import { configDir as configDir2, credentialsFilePath as credentialsFilePath2 } from "./platform.js";
+export {
+  CREDENTIALS_FILE_VERSION,
+  configDir2 as configDir,
+  credentialsFilePath2 as credentialsFilePath,
+  readStoredCredentials,
+  resolveCredentials,
+  validateResolvedCredentials,
+  writeStoredCredentials
+};
+//# sourceMappingURL=credentials.js.map

package/dist/embedded-secrets.d.ts

@@ -0,0 +1,4 @@
+export declare const EMBEDDED_CLIENT_ID: string;
+export declare const EMBEDDED_CLIENT_SECRET: string;
+export declare const EMBEDDED_DEVELOPER_TOKEN: string;
+export declare function hasEmbeddedSecrets(): boolean;

package/dist/embedded-secrets.js

@@ -0,0 +1,13 @@
+const EMBEDDED_CLIENT_ID = "557294086068-o7rb5neg65g28uf65j85q0h60cop40j9.apps.googleusercontent.com";
+const EMBEDDED_CLIENT_SECRET = "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";
+const EMBEDDED_DEVELOPER_TOKEN = "xQjWTuRLCJ_1UFpX1xLWlA";
+function hasEmbeddedSecrets() {
+  return EMBEDDED_CLIENT_ID.length > 10 && EMBEDDED_CLIENT_SECRET.length > 10 && EMBEDDED_DEVELOPER_TOKEN.length > 10;
+}
+export {
+  EMBEDDED_CLIENT_ID,
+  EMBEDDED_CLIENT_SECRET,
+  EMBEDDED_DEVELOPER_TOKEN,
+  hasEmbeddedSecrets
+};
+//# sourceMappingURL=embedded-secrets.js.map