mcp-google-ads 1.3.0 → 1.4.0

package/README.md

@@ -103,6 +103,18 @@ Alternatively, set credentials via environment variables (these override `config
 | `GOOGLE_ADS_CLIENT_ID` | Yes | OAuth 2.0 client ID |
 | `GOOGLE_ADS_CLIENT_SECRET` | Yes | OAuth 2.0 client secret |
 | `GOOGLE_ADS_REFRESH_TOKEN` | Yes | OAuth 2.0 refresh token |
+| `GOOGLE_ADS_MCP_WRITE` | No | Set to `true` to expose mutating tools (create/update/pause/enable/remove/apply). Default: read-only. |
+
+### Read-only by default
+
+The server ships read-only. Mutating tools (anything that creates, updates,
+pauses, enables, removes, links, or applies) are hidden from the tool list
+until you set `GOOGLE_ADS_MCP_WRITE=true` in the MCP server environment.
+If a write tool is somehow invoked without that flag, the server returns a
+clear error pointing at the env var.
+
+This is deliberate: a casual chat message like "activate the Fundraising
+campaign" should not move live ad spend without an explicit opt-in.
 
 ### 4. Add to Claude Code
 

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "a2cf43a",
-  "builtAt": "2026-04-17T21:13:12.209Z",
+  "sha": "94b326c",
+  "builtAt": "2026-04-18T17:26:41.136Z",
   "embeddedSecrets": true
 }

package/dist/campaignBuilder.js

@@ -23,7 +23,7 @@ function buildCampaignCreatePayload(input) {
     campaign.network_settings = {
       target_google_search: false,
       target_search_network: false,
-      target_content_network: false,
+      target_content_network: true,
       target_partner_search_network: false
     };
   }

package/dist/index.js

@@ -11,6 +11,11 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { tools } from "./tools.js";
+import {
+  assertWriteAllowed,
+  filterTools,
+  isWriteEnabled
+} from "./writeGate.js";
 import { validateRsa } from "./validateRsa.js";
 import {
   validateRemoveInput,
@@ -36,7 +41,8 @@ import {
 } from "./imageAsset.js";
 import {
   validateDemandGenAd,
-  buildDemandGenAdPayload
+  buildDemandGenAdPayload,
+  isDemandGenAdGroup
 } from "./validateDemandGenAd.js";
 import { GoogleAdsApi, enums } from "google-ads-api";
 import { readFileSync, existsSync } from "fs";
@@ -729,7 +735,7 @@ class GoogleAdsManager {
     const cleanId = customerId.replace(/-/g, "");
     const agRows = await withResilience(
       () => customer.query(
-        `SELECT ad_group.id, ad_group.type FROM ad_group WHERE ad_group.id = ${sanitizeNumericId(
+        `SELECT ad_group.id, ad_group.type, campaign.advertising_channel_type FROM ad_group WHERE ad_group.id = ${sanitizeNumericId(
           input.ad_group_id
         )}`
       ),
@@ -738,11 +744,11 @@ class GoogleAdsManager {
     if (!agRows || agRows.length === 0) {
       throw new Error(`Ad group ${input.ad_group_id} not found`);
     }
-    const agType = agRows[0]?.ad_group?.type;
-    const isDgAdGroup = agType === 21 || agType === "DEMAND_GEN_MULTI_ASSET_AD_GROUP" || agType === "21";
-    if (!isDgAdGroup) {
+    if (!isDemandGenAdGroup(agRows[0])) {
+      const agType = agRows[0]?.ad_group?.type;
+      const cType = agRows[0]?.campaign?.advertising_channel_type;
       throw new Error(
-        `Ad group ${input.ad_group_id} has type '${agType}', not DEMAND_GEN_MULTI_ASSET_AD_GROUP. Use google_ads_create_ad_group with type=DEMAND_GEN_MULTI_ASSET_AD_GROUP first.`
+        `Ad group ${input.ad_group_id} is not a Demand Gen ad group (ad_group.type='${agType}', campaign.advertising_channel_type='${cType}'). It must belong to a DEMAND_GEN campaign.`
       );
     }
     const payload = buildDemandGenAdPayload({
@@ -1637,11 +1643,12 @@ const server = new Server(
   }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return { tools };
+  return { tools: filterTools(tools) };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
   try {
+    assertWriteAllowed(name);
     switch (name) {
       case "google_ads_get_client_context": {
         const cwd = args?.working_directory;
@@ -2598,6 +2605,11 @@ async function main() {
       logger.warn({ error: err.message }, "Auth check returned non-auth error (may be OK)");
     }
   }
+  const writeMode = isWriteEnabled();
+  logger.info(
+    { writeEnabled: writeMode, envVar: "GOOGLE_ADS_MCP_WRITE" },
+    writeMode ? "Write operations ENABLED (mutating tools exposed)" : "Read-only mode (write tools hidden -- set GOOGLE_ADS_MCP_WRITE=true to enable)"
+  );
   const transport = new StdioServerTransport();
   await server.connect(transport);
   logger.info("MCP Google Ads server running");

package/dist/validateDemandGenAd.d.ts

@@ -60,3 +60,15 @@ export declare function buildDemandGenAdPayload(args: {
     input: DemandGenAdInput;
 }): DemandGenAdPayload;
 export declare function validateDemandGenAd(ad: DemandGenAdInput): DemandGenAdValidationResult;
+/**
+ * Decide whether a GAQL row describes a Demand Gen ad group. Accepts two
+ * orthogonal signals:
+ *   1) ad_group.type matches DEMAND_GEN_MULTI_ASSET_AD_GROUP (proto value 21
+ *      or its string name when future libs add it).
+ *   2) campaign.advertising_channel_type === DEMAND_GEN (14). This is the
+ *      authoritative check because DG campaigns can only contain DG ad groups,
+ *      and google-ads-api v23 returns undefined for ad_group.type when the
+ *      stored proto value isn't in its local enum map.
+ */
+export declare function isDemandGenAdGroup(row: any): boolean;
+export declare function normalizeCallToAction(input: string): string;

package/dist/validateDemandGenAd.js

@@ -12,7 +12,7 @@ function buildDemandGenAdPayload(args) {
   const assetRef = (id) => ({ asset: `customers/${customer_id_clean}/assets/${id}` });
   const dgAd = {
     business_name: input.business_name,
-    call_to_action_text: input.call_to_action,
+    call_to_action_text: normalizeCallToAction(input.call_to_action),
     marketing_images: input.marketing_image_asset_ids.map(assetRef),
     headlines: input.headlines.map((h) => ({ text: headlineText(h) })),
     descriptions: input.descriptions.map((t) => ({ text: t }))
@@ -83,6 +83,37 @@ function validateDemandGenAd(ad) {
   });
   return { valid: errors.length === 0, errors };
 }
+const DEMAND_GEN_CHANNEL_TYPE = 14;
+function isDemandGenAdGroup(row) {
+  if (!row) return false;
+  const agType = row.ad_group?.type;
+  const campaignChannelType = row.campaign?.advertising_channel_type;
+  return agType === 21 || agType === "21" || agType === "DEMAND_GEN_MULTI_ASSET_AD_GROUP" || campaignChannelType === DEMAND_GEN_CHANNEL_TYPE || campaignChannelType === "DEMAND_GEN";
+}
+const CTA_DISPLAY_MAP = {
+  LEARN_MORE: "Learn more",
+  GET_QUOTE: "Get quote",
+  APPLY_NOW: "Apply now",
+  SIGN_UP: "Sign up",
+  CONTACT_US: "Contact us",
+  SUBSCRIBE: "Subscribe",
+  DOWNLOAD: "Download",
+  BOOK_NOW: "Book now",
+  SHOP_NOW: "Shop now",
+  BUY_NOW: "Buy now",
+  DONATE_NOW: "Donate now",
+  ORDER_NOW: "Order now",
+  PLAY_NOW: "Play now",
+  SEE_MORE: "See more",
+  START_NOW: "Start now",
+  VISIT_SITE: "Visit site",
+  WATCH_NOW: "Watch now"
+};
+function normalizeCallToAction(input) {
+  if (!input) return input;
+  const key = input.toUpperCase();
+  return CTA_DISPLAY_MAP[key] ?? input;
+}
 export {
   MAX_DESCRIPTIONS,
   MAX_DESCRIPTION_LEN,
@@ -91,6 +122,8 @@ export {
   MAX_LONG_HEADLINES,
   MAX_LONG_HEADLINE_LEN,
   buildDemandGenAdPayload,
+  isDemandGenAdGroup,
+  normalizeCallToAction,
   validateDemandGenAd
 };
 //# sourceMappingURL=validateDemandGenAd.js.map

package/dist/writeGate.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Tools that mutate Google Ads state. These are hidden from the tool list
+ * and refused at call time unless GOOGLE_ADS_MCP_WRITE=true.
+ *
+ * Adding a new tool? Put it in this set if it creates, modifies, pauses,
+ * enables, removes, links, unlinks, or applies anything.
+ */
+export declare const WRITE_TOOLS: ReadonlySet<string>;
+export declare function isWriteTool(name: string): boolean;
+export declare function isWriteEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function filterTools(allTools: readonly Tool[], env?: NodeJS.ProcessEnv): Tool[];
+export declare const WRITE_DISABLED_MESSAGE = "Write operations are disabled. Set GOOGLE_ADS_MCP_WRITE=true in the MCP server environment to enable mutating tools (create/update/pause/enable/remove/apply).";
+/**
+ * Assert that a tool call is allowed under the current write-mode setting.
+ * Throws a clear Error if the tool mutates state and writes are disabled.
+ */
+export declare function assertWriteAllowed(toolName: string, env?: NodeJS.ProcessEnv): void;

package/dist/writeGate.js

@@ -0,0 +1,54 @@
+const WRITE_TOOLS = /* @__PURE__ */ new Set([
+  "google_ads_create_campaign",
+  "google_ads_create_ad_group",
+  "google_ads_create_responsive_search_ad",
+  "google_ads_create_keywords",
+  "google_ads_create_shared_set",
+  "google_ads_create_demand_gen_multi_asset_ad",
+  "google_ads_create_image_asset",
+  "google_ads_enable_items",
+  "google_ads_pause_items",
+  "google_ads_pause_keywords",
+  "google_ads_pause_asset_links",
+  "google_ads_remove_items",
+  "google_ads_remove_shared_negatives",
+  "google_ads_remove_campaign_negatives",
+  "google_ads_remove_adgroup_negatives",
+  "google_ads_add_shared_negatives",
+  "google_ads_add_campaign_negatives",
+  "google_ads_link_shared_set",
+  "google_ads_unlink_shared_set",
+  "google_ads_apply_label",
+  "google_ads_update_campaign_tracking",
+  "google_ads_update_campaign_budget",
+  "google_ads_update_campaign_bidding",
+  "google_ads_update_asset_urls"
+]);
+function isWriteTool(name) {
+  return WRITE_TOOLS.has(name);
+}
+function isWriteEnabled(env = process.env) {
+  const v = (env.GOOGLE_ADS_MCP_WRITE || "").trim().toLowerCase();
+  return v === "true" || v === "1" || v === "yes";
+}
+function filterTools(allTools, env = process.env) {
+  if (isWriteEnabled(env)) return [...allTools];
+  return allTools.filter((t) => !WRITE_TOOLS.has(t.name));
+}
+const WRITE_DISABLED_MESSAGE = "Write operations are disabled. Set GOOGLE_ADS_MCP_WRITE=true in the MCP server environment to enable mutating tools (create/update/pause/enable/remove/apply).";
+function assertWriteAllowed(toolName, env = process.env) {
+  if (!isWriteTool(toolName)) return;
+  if (isWriteEnabled(env)) return;
+  throw new Error(
+    `Tool "${toolName}" is a write operation. ${WRITE_DISABLED_MESSAGE}`
+  );
+}
+export {
+  WRITE_DISABLED_MESSAGE,
+  WRITE_TOOLS,
+  assertWriteAllowed,
+  filterTools,
+  isWriteEnabled,
+  isWriteTool
+};
+//# sourceMappingURL=writeGate.js.map

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "mcp-google-ads",
   "mcpName": "io.github.mharnett/google-ads",
-  "version": "1.3.0",
-  "description": "MCP server for Google Ads API with MCC support, 36 tools for campaign management, reporting, and optimization -- now includes Demand Gen campaign creation end-to-end. Safe by default -- all changes created PAUSED.",
+  "version": "1.4.0",
+  "description": "MCP server for Google Ads API with MCC support, 41 tools for campaign management, reporting, and optimization. Read-only by default -- mutating tools require GOOGLE_ADS_MCP_WRITE=true. All creates/updates land PAUSED.",
   "main": "dist/index.js",
   "bin": {
     "mcp-google-ads": "dist/index.js",