mcp-google-ads 1.7.0 → 1.8.0

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "95e7b7c",
-  "builtAt": "2026-07-09T13:47:57.357Z",
+  "sha": "b3b7dab",
+  "builtAt": "2026-07-20T18:35:03.765Z",
   "embeddedSecrets": true
 }

package/dist/index.d.ts

@@ -144,6 +144,48 @@ export declare class GoogleAdsManager {
         ad_id: string | undefined;
         updated_fields: string[];
     }>;
+    /**
+     * Add/replace YouTube videos on an existing video responsive ad (VIDEO
+     * channel). Campaign-level VIDEO mutates are MUTATE_NOT_ALLOWED, but the
+     * ad-level `video_responsive_ad.videos` update via the `ads` resource is
+     * legal and edits in place (same ad ID) — verified live 2026-07-18.
+     */
+    updateVideoAdVideos(customerId: string, input: {
+        ad_id: string;
+        videos: string[];
+        mode?: "append" | "replace";
+        skip_visibility_check?: boolean;
+    }): Promise<{
+        success: boolean;
+        unchanged: boolean;
+        ad_id: string;
+        ad_resource_name: string;
+        mode: "replace" | "append";
+        videos_before: number;
+        videos_after: number;
+        added_assets: string[];
+        skipped_existing: string[];
+        created_assets: string[];
+        video_titles: {
+            [k: string]: string | null;
+        };
+        message: string;
+    } | {
+        success: boolean;
+        unchanged: boolean;
+        ad_id: string;
+        ad_resource_name: string;
+        mode: "replace" | "append";
+        videos_before: number;
+        videos_after: number;
+        added_assets: string[];
+        skipped_existing: string[];
+        created_assets: string[];
+        video_titles: {
+            [k: string]: string | null;
+        };
+        message?: undefined;
+    }>;
     createKeywords(customerId: string, keywords: {
         ad_group_id: string;
         keywords: Array<{

package/dist/index.js

@@ -47,6 +47,12 @@ import {
 import {
   buildAdGroupCreatePayload
 } from "./adGroupBuilder.js";
+import {
+  buildVideoAdUpdateResource,
+  checkYoutubeVisibility,
+  planVideoUpdate,
+  validateYoutubeVideoInputs
+} from "./videoAdVideos.js";
 import {
   prepareImageForUpload
 } from "./imageAsset.js";
@@ -949,7 +955,9 @@ class GoogleAdsManager {
       const adId = resourceName;
       const adRows = await withResilience(
         () => customer.query(
-          `SELECT ad_group_ad.resource_name FROM ad_group_ad WHERE ad_group_ad.id = ${sanitizeNumericId(
+          // ad_group_ad has no queryable `.id`; the ad's numeric ID lives at
+          // ad_group_ad.ad.id. (Using ad_group_ad.id fails with query_error 32.)
+          `SELECT ad_group_ad.resource_name FROM ad_group_ad WHERE ad_group_ad.ad.id = ${sanitizeNumericId(
             adId
           )}`
         ),
@@ -1027,6 +1035,150 @@ class GoogleAdsManager {
       updated_fields: Object.keys(input).filter((k) => k !== "labels" && input[k])
     };
   }
+  /**
+   * Add/replace YouTube videos on an existing video responsive ad (VIDEO
+   * channel). Campaign-level VIDEO mutates are MUTATE_NOT_ALLOWED, but the
+   * ad-level `video_responsive_ad.videos` update via the `ads` resource is
+   * legal and edits in place (same ad ID) — verified live 2026-07-18.
+   */
+  async updateVideoAdVideos(customerId, input) {
+    const customer = this.getCustomer(customerId);
+    const cleanId = customerId.replace(/-/g, "");
+    const mode = input.mode ?? "append";
+    const parsed = validateYoutubeVideoInputs(input.videos);
+    if (!parsed.valid) {
+      throw new Error("Video input validation failed:\n" + parsed.errors.join("\n"));
+    }
+    let adId = input.ad_id.trim();
+    const rnMatch = adId.match(/^customers\/\d+\/ads\/(\d+)$/);
+    if (rnMatch) adId = rnMatch[1];
+    if (!/^\d+$/.test(adId)) {
+      throw new Error(
+        `ad_id must be a numeric ad ID or customers/X/ads/Y resource name, got "${input.ad_id}"`
+      );
+    }
+    const adRows = await withResilience(
+      () => customer.query(
+        `SELECT ad_group_ad.resource_name, ad_group_ad.ad.type, ad_group_ad.ad.name,
+                  ad_group_ad.ad.video_responsive_ad.videos
+           FROM ad_group_ad
+           WHERE ad_group_ad.ad.id = ${sanitizeNumericId(adId)}
+             AND ad_group_ad.status != 'REMOVED'`
+      ),
+      "updateVideoAdVideos.fetchAd"
+    );
+    if (!adRows || adRows.length === 0) {
+      throw new Error(`Ad ${adId} not found (or removed)`);
+    }
+    const adRow = adRows[0];
+    const adType = adRow?.ad_group_ad?.ad?.type;
+    if (adType !== enums.AdType.VIDEO_RESPONSIVE_AD && adType !== "VIDEO_RESPONSIVE_AD") {
+      throw new Error(
+        `Ad ${adId} is not a VIDEO_RESPONSIVE_AD (type=${adType}). This tool only manages videos on video responsive ads.`
+      );
+    }
+    const adGroupAdRN = adRow.ad_group_ad.resource_name;
+    const currentVideos = (adRow.ad_group_ad.ad.video_responsive_ad?.videos ?? []).map((v) => v.asset);
+    const visibility = {};
+    if (!input.skip_visibility_check) {
+      for (const videoId of parsed.ids) {
+        const check = await checkYoutubeVisibility(videoId);
+        visibility[videoId] = check;
+        if (check.visible === false) {
+          throw new Error(check.reason ?? `Video ${videoId} is not visible`);
+        }
+      }
+    }
+    const idList = parsed.ids.map((id) => `'${id}'`).join(", ");
+    const assetRows = await withResilience(
+      () => customer.query(
+        `SELECT asset.resource_name, asset.youtube_video_asset.youtube_video_id
+           FROM asset
+           WHERE asset.youtube_video_asset.youtube_video_id IN (${idList})`
+      ),
+      "updateVideoAdVideos.findAssets"
+    );
+    const assetByVideoId = /* @__PURE__ */ new Map();
+    for (const row of assetRows) {
+      const vid = row?.asset?.youtube_video_asset?.youtube_video_id;
+      if (vid && !assetByVideoId.has(vid)) assetByVideoId.set(vid, row.asset.resource_name);
+    }
+    const toCreate = parsed.ids.filter((id) => !assetByVideoId.has(id));
+    const createdAssets = [];
+    if (toCreate.length > 0) {
+      const createResp = await withResilience(
+        () => customer.assets.create(
+          toCreate.map((videoId) => {
+            const title = visibility[videoId]?.title ?? `YouTube video ${videoId}`;
+            return {
+              name: title,
+              type: enums.AssetType.YOUTUBE_VIDEO,
+              youtube_video_asset: {
+                youtube_video_id: videoId,
+                youtube_video_title: title
+              }
+            };
+          })
+        ),
+        "updateVideoAdVideos.createAssets"
+      );
+      const createResults = createResp.results || [];
+      createResults.forEach((r, i) => {
+        assetByVideoId.set(toCreate[i], r.resource_name);
+        createdAssets.push(r.resource_name);
+      });
+    }
+    const requestedRNs = parsed.ids.map((id) => assetByVideoId.get(id)).filter(Boolean);
+    const plan = planVideoUpdate(currentVideos, requestedRNs, mode);
+    if (plan.videos.length === 0) {
+      throw new Error("Refusing to leave the ad with zero videos (mode=replace with empty target).");
+    }
+    if (plan.unchanged) {
+      return {
+        success: true,
+        unchanged: true,
+        ad_id: adId,
+        ad_resource_name: `customers/${cleanId}/ads/${adId}`,
+        mode,
+        videos_before: currentVideos.length,
+        videos_after: plan.videos.length,
+        added_assets: [],
+        skipped_existing: plan.skipped_existing,
+        created_assets: createdAssets,
+        video_titles: Object.fromEntries(
+          Object.entries(visibility).map(([id, v]) => [id, v.title ?? null])
+        ),
+        message: "All requested videos are already on the ad \u2014 no mutate sent."
+      };
+    }
+    const resource = buildVideoAdUpdateResource(cleanId, adId, plan.videos);
+    await withResilience(
+      () => customer.mutateResources([
+        {
+          entity: "ad",
+          operation: "update",
+          resource
+        }
+      ]),
+      "updateVideoAdVideos"
+    );
+    await this.autoLabelCreated(customerId, [adGroupAdRN], "ad");
+    return {
+      success: true,
+      unchanged: false,
+      ad_id: adId,
+      ad_resource_name: `customers/${cleanId}/ads/${adId}`,
+      mode,
+      videos_before: currentVideos.length,
+      videos_after: plan.videos.length,
+      added_assets: plan.added,
+      skipped_existing: plan.skipped_existing,
+      created_assets: createdAssets,
+      video_titles: Object.fromEntries(
+        Object.entries(visibility).map(([id, v]) => [id, v.title ?? null])
+      )
+    };
+  }
   // Create keywords (paused by default, auto-labeled for discoverability)
   async createKeywords(customerId, keywords) {
     const customer = this.getCustomer(customerId);
@@ -4101,6 +4253,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         try {
           const result = await getAdsManager().createDemandGenMultiAssetAd(customerId, {
             ad_group_id: args?.ad_group_id,
+            name: args?.name,
             final_urls: args?.final_urls,
             business_name: args?.business_name,
             call_to_action: args?.call_to_action,
@@ -4160,6 +4313,33 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           };
         }
       }
+      case "google_ads_update_video_ad_videos": {
+        const customerId = args?.customer_id || "";
+        try {
+          const result = await getAdsManager().updateVideoAdVideos(customerId, {
+            ad_id: args?.ad_id,
+            videos: args?.videos,
+            mode: args?.mode,
+            skip_visibility_check: args?.skip_visibility_check
+          });
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                ...result,
+                message: result.message ?? `Video ad updated in place: ${result.videos_before} \u2192 ${result.videos_after} videos (${result.added_assets.length} added).`
+              }, null, 2)
+            }]
+          };
+        } catch (e) {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({ success: false, error: e.message }, null, 2)
+            }]
+          };
+        }
+      }
       case "google_ads_create_page_feed": {
         const customerId = args?.customer_id || "";
         const campaignId = args?.campaign_id;

package/dist/tools.js

@@ -1014,6 +1014,10 @@ const tools = [
       properties: {
         customer_id: { type: "string" },
         ad_group_id: { type: "string" },
+        name: {
+          type: "string",
+          description: "Optional internal ad name (not user-facing) shown in the UI's Ad column \u2014 e.g. 'Gartner CIO AI - NAM Gov'. Set it to avoid the generic auto-name ('Ad 1'). NOTE: immutable after creation on DG multi-asset ads, so set it here."
+        },
         final_urls: { type: "array", items: { type: "string" } },
         business_name: { type: "string" },
         call_to_action: {
@@ -1085,7 +1089,7 @@ const tools = [
   },
   {
     name: "google_ads_update_demand_gen_multi_asset_ad",
-    description: "Update headlines, long_headlines, or descriptions on an existing Demand Gen Multi-Asset ad (PAUSED or ENABLED). Validates character/count limits before the API call. Provide the ad's resource name (customers/XXX/adGroupAds/YYY~ZZZ) or numeric ad ID. Omit fields you don't want to change. Auto-labels with Claude-MM-DD-YY. Use this to fix copy, test variants, or adjust messaging without recreating ads.",
+    description: "Attempt to update copy on a Demand Gen ad. WARNING: on Demand Gen MULTI-ASSET ads the entire creative \u2014 headlines, descriptions, AND images \u2014 is IMMUTABLE after creation; the Google Ads API rejects any such update with IMMUTABLE_FIELD (verified live 2026-07-12). To change ANY creative on a multi-asset ad you must RECREATE it (create a new ad + pause the old one), not update it. This tool is retained for DG ad formats that may permit copy edits; against a multi-asset ad it will error. Provide the ad's resource name (customers/XXX/adGroupAds/YYY~ZZZ) or numeric ad ID.",
     inputSchema: {
       additionalProperties: false,
       type: "object",
@@ -1134,6 +1138,36 @@ const tools = [
       ]
     }
   },
+  {
+    name: "google_ads_update_video_ad_videos",
+    description: "Add or replace the YouTube videos on an existing video responsive ad (VIDEO campaigns, e.g. YouTube reach). The VIDEO channel is campaign-level API-locked, but AD-level video_responsive_ad.videos updates ARE allowed and edit the ad in place (same ad ID) \u2014 verified live 2026-07-18. Accepts YouTube URLs (watch/shorts/youtu.be/embed) or 11-char video IDs; finds-or-creates the YouTube video assets; preflights each new video via oEmbed (private videos are rejected by Google Ads \u2014 must be Public or Unlisted). Default mode 'append' keeps existing videos and adds new ones. Auto-labels the ad claude-MM-DD-YY.",
+    inputSchema: {
+      additionalProperties: false,
+      type: "object",
+      properties: {
+        customer_id: { type: "string" },
+        ad_id: {
+          type: "string",
+          description: "Numeric ad ID (e.g. 815638860130) or full ads resource name (customers/XXX/ads/YYY). Must be a VIDEO_RESPONSIVE_AD."
+        },
+        videos: {
+          type: "array",
+          items: { type: "string" },
+          description: "YouTube video URLs or 11-char video IDs to add (or, with mode=replace, the complete target list)."
+        },
+        mode: {
+          type: "string",
+          enum: ["append", "replace"],
+          description: "append (default): keep current videos, add new ones. replace: the ad ends up with exactly the given list."
+        },
+        skip_visibility_check: {
+          type: "boolean",
+          description: "Skip the oEmbed public/unlisted preflight (e.g. offline testing). Default false."
+        }
+      },
+      required: ["customer_id", "ad_id", "videos"]
+    }
+  },
   {
     name: "google_ads_create_page_feed",
     description: "Create an AI Max / DSA page feed (AssetSet of type PAGE_FEED) and attach it to a campaign. Each URL becomes a PageFeedAsset tagged with the given label. Use this to constrain AI Max final-URL expansion to a specific list of landing pages. Returns the AssetSet resource name and the number of URLs added.",

package/dist/validateDemandGenAd.d.ts

@@ -14,6 +14,9 @@ export interface DemandGenAdInput {
     final_urls: string[];
     business_name: string;
     call_to_action: string;
+    /** Optional internal ad name (not user-facing). Set once at creation —
+     *  ad.name is immutable on DG multi-asset ads after create. */
+    name?: string;
     marketing_image_asset_ids?: string[];
     square_marketing_image_asset_ids?: string[];
     portrait_marketing_image_asset_ids?: string[];
@@ -50,6 +53,7 @@ export interface DemandGenAdPayload {
     ad_group: string;
     status: number;
     ad: {
+        name?: string;
         final_urls: string[];
         demand_gen_multi_asset_ad: Record<string, any>;
     };

package/dist/validateDemandGenAd.js

@@ -31,13 +31,17 @@ function buildDemandGenAdPayload(args) {
   if (input.long_headlines?.length) {
     dgAd.long_headlines = input.long_headlines.map((t) => ({ text: t }));
   }
+  const ad = {
+    final_urls: input.final_urls,
+    demand_gen_multi_asset_ad: dgAd
+  };
+  if (input.name) {
+    ad.name = input.name;
+  }
   return {
     ad_group: `customers/${customer_id_clean}/adGroups/${ad_group_id}`,
     status: 3,
-    ad: {
-      final_urls: input.final_urls,
-      demand_gen_multi_asset_ad: dgAd
-    }
+    ad
   };
 }
 function validateDemandGenAd(ad) {

package/dist/videoAdVideos.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Video responsive ad video management — pure helpers.
+ *
+ * Platform reality (verified live 2026-07-18): the Google Ads API rejects
+ * every campaign-level mutate on the VIDEO channel (MUTATE_NOT_ALLOWED),
+ * but AD-level updates of `video_responsive_ad.videos` succeed and edit the
+ * ad in place (same ad ID). Source videos must be Public or Unlisted on
+ * YouTube — private videos are rejected / stop serving, and their oEmbed
+ * endpoint returns 401/403, which is the cheap preflight fingerprint.
+ */
+/**
+ * Extract an 11-char YouTube video ID from a bare ID or any common URL form
+ * (youtu.be/, watch?v=, /shorts/, /embed/). Returns null if unparseable.
+ */
+export declare function parseYoutubeVideoId(input: string): string | null;
+/**
+ * Parse + validate a list of user-supplied video URLs/IDs.
+ * Errors on unparseable entries, duplicates (after normalization), and
+ * empty input. `ids` preserves input order.
+ */
+export declare function validateYoutubeVideoInputs(inputs: string[]): {
+    valid: boolean;
+    ids: string[];
+    errors: string[];
+};
+/**
+ * Compute the target video-asset list for the update.
+ * append: current list first (order preserved), then genuinely new assets.
+ * replace: exactly the requested list (deduped, order preserved).
+ */
+export declare function planVideoUpdate(currentAssetRNs: string[], requestedAssetRNs: string[], mode: "append" | "replace"): {
+    videos: string[];
+    added: string[];
+    skipped_existing: string[];
+    unchanged: boolean;
+};
+/**
+ * Build the mutate resource for the ad-level update. NOTE: the target is the
+ * `ads` resource (customers/X/ads/Y), NOT `adGroupAds` — this is what makes
+ * the mutate legal on the VIDEO channel.
+ */
+export declare function buildVideoAdUpdateResource(customerId: string, adId: string, assetResourceNames: string[]): {
+    resource_name: string;
+    video_responsive_ad: {
+        videos: Array<{
+            asset: string;
+        }>;
+    };
+};
+export interface VisibilityResult {
+    visible: boolean | null;
+    title?: string;
+    reason?: string;
+}
+/**
+ * Best-effort preflight: YouTube's oEmbed endpoint returns 200 (+ title) for
+ * Public/Unlisted videos and 401/403 for private or unavailable ones. On
+ * network failure the check is indeterminate — never blocks the mutate.
+ */
+export declare function checkYoutubeVisibility(videoId: string, fetchFn?: typeof fetch): Promise<VisibilityResult>;

package/dist/videoAdVideos.js

@@ -0,0 +1,100 @@
+const VIDEO_ID_RE = /^[A-Za-z0-9_-]{11}$/;
+function parseYoutubeVideoId(input) {
+  const trimmed = (input ?? "").trim();
+  if (!trimmed) return null;
+  if (VIDEO_ID_RE.test(trimmed)) return trimmed;
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  const host = url.hostname.replace(/^www\./, "");
+  let candidate = null;
+  if (host === "youtu.be") {
+    candidate = url.pathname.split("/").filter(Boolean)[0] ?? null;
+  } else if (host === "youtube.com" || host === "m.youtube.com" || host === "music.youtube.com") {
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (segments[0] === "watch") {
+      candidate = url.searchParams.get("v");
+    } else if (segments[0] === "shorts" || segments[0] === "embed" || segments[0] === "live") {
+      candidate = segments[1] ?? null;
+    }
+  }
+  return candidate && VIDEO_ID_RE.test(candidate) ? candidate : null;
+}
+function validateYoutubeVideoInputs(inputs) {
+  const errors = [];
+  const ids = [];
+  if (!inputs || inputs.length === 0) {
+    return { valid: false, ids, errors: ["No videos provided"] };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const input of inputs) {
+    const id = parseYoutubeVideoId(input);
+    if (!id) {
+      errors.push(`Not a YouTube video URL or 11-char video ID: "${input}"`);
+      continue;
+    }
+    if (seen.has(id)) {
+      errors.push(`Duplicate video: "${input}" resolves to ${id}, already in the list`);
+      continue;
+    }
+    seen.add(id);
+    ids.push(id);
+  }
+  return { valid: errors.length === 0, ids, errors };
+}
+function planVideoUpdate(currentAssetRNs, requestedAssetRNs, mode) {
+  const current = [...currentAssetRNs];
+  const requested = [...new Set(requestedAssetRNs)];
+  const currentSet = new Set(current);
+  let videos;
+  if (mode === "replace") {
+    videos = requested;
+  } else {
+    videos = [...current, ...requested.filter((rn) => !currentSet.has(rn))];
+  }
+  const added = videos.filter((rn) => !currentSet.has(rn));
+  const skipped_existing = mode === "append" ? requested.filter((rn) => currentSet.has(rn)) : [];
+  const unchanged = videos.length === current.length && videos.every((rn, i) => rn === current[i]);
+  return { videos, added, skipped_existing, unchanged };
+}
+function buildVideoAdUpdateResource(customerId, adId, assetResourceNames) {
+  const cleanId = customerId.replace(/-/g, "");
+  return {
+    resource_name: `customers/${cleanId}/ads/${adId}`,
+    video_responsive_ad: {
+      videos: assetResourceNames.map((asset) => ({ asset }))
+    }
+  };
+}
+async function checkYoutubeVisibility(videoId, fetchFn = fetch) {
+  try {
+    const resp = await fetchFn(
+      `https://www.youtube.com/oembed?url=https://www.youtube.com/watch?v=${videoId}&format=json`
+    );
+    if (resp.ok) {
+      let title;
+      try {
+        title = (await resp.json())?.title;
+      } catch {
+      }
+      return { visible: true, title };
+    }
+    return {
+      visible: false,
+      reason: `YouTube oEmbed returned ${resp.status} \u2014 video ${videoId} looks private or unavailable. Ads require Public or Unlisted videos.`
+    };
+  } catch (e) {
+    return { visible: null, reason: `visibility check failed: ${e?.message ?? e}` };
+  }
+}
+export {
+  buildVideoAdUpdateResource,
+  checkYoutubeVisibility,
+  parseYoutubeVideoId,
+  planVideoUpdate,
+  validateYoutubeVideoInputs
+};
+//# sourceMappingURL=videoAdVideos.js.map

package/dist/writeGate.js

@@ -7,6 +7,7 @@ const WRITE_TOOLS = /* @__PURE__ */ new Set([
   "google_ads_create_shared_set",
   "google_ads_create_demand_gen_multi_asset_ad",
   "google_ads_update_demand_gen_multi_asset_ad",
+  "google_ads_update_video_ad_videos",
   "google_ads_create_image_asset",
   "google_ads_create_lead_form_asset",
   "google_ads_enable_items",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-google-ads",
   "mcpName": "io.github.mharnett/google-ads",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "MCP server for Google Ads API with MCC support, 44 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": {