add_keywords

Add keywords to Google Ads campaigns or ad groups to improve targeting and reach. Specify match types like exact, phrase, or broad for precise ad placement.

Instructions

Add keywords to a Google Ads campaign or ad group.

Input Schema

TableJSON Schema

Name	Required	Description
`ad_group_id`	Yes	Ad group ID to add keywords to
`keywords`	Yes	Keywords to add
`match_type`	No	Keyword match type (default: PHRASE)

Implementation Reference

src/index.ts:809-818 (handler)

The argMapper function for 'add_keywords' tool that transforms input arguments (ad_group_id, keywords, match_type) into CLI arguments for the 'google_ads_add_keywords' script. This is the core handler logic that maps tool inputs to script execution parameters.

add_keywords: {
  script: "google_ads_add_keywords",
  platform: "google",
  argMapper: (a) => {
    const cliArgs: string[] = ["--ad-group-id", a.ad_group_id as string];
    (a.keywords as string[] || []).forEach((k) => cliArgs.push("--keyword", k));
    if (a.match_type) cliArgs.push("--match-type", a.match_type as string);
    return cliArgs;
  },
},

src/index.ts:701-956 (handler)

The main handleTool function that processes all tool calls. It contains toolMappings object with script names and argMapper functions, then calls the Synter API with the mapped arguments. The add_keywords entry is at lines 809-818 within this mapping.

async function handleTool(
  name: string,
  args: ToolArgs
): Promise<Record<string, unknown>> {
  // Map tool names to script names and handle parameters
  const toolMappings: Record<string, { script: string; platform?: string; argMapper?: (args: ToolArgs) => string[] }> = {
    // Campaign management
    list_campaigns: {
      script: "google_ads_list_campaigns",
      platform: (args.platform as string) || "google",
      argMapper: (a) => {
        const cliArgs: string[] = [];
        if (a.status) cliArgs.push("--status", a.status as string);
        if (a.limit) cliArgs.push("--limit", String(a.limit));
        return cliArgs;
      },
    },
    create_search_campaign: {
      script: "google_ads_create_search_campaign",
      platform: "google",
      argMapper: (a) => {
        const cliArgs: string[] = [
          "--campaign-name", a.campaign_name as string,
          "--daily-budget", String(a.daily_budget),
          "--final-url", a.final_url as string,
        ];
        (a.keywords as string[] || []).forEach((k) => cliArgs.push("--keyword", k));
        (a.headlines as string[] || []).forEach((h) => cliArgs.push("--headline", h));
        (a.descriptions as string[] || []).forEach((d) => cliArgs.push("--description", d));
        (a.geo_targets as string[] || []).forEach((g) => cliArgs.push("--geo-targets", g));
        return cliArgs;
      },
    },
    create_display_campaign: {
      script: "google_ads_create_display_campaign",
      platform: "google",
      argMapper: (a) => {
        const cliArgs: string[] = [
          "--campaign-name", a.campaign_name as string,
          "--daily-budget", String(a.daily_budget),
          "--business-name", a.business_name as string,
          "--final-url", a.final_url as string,
        ];
        if (a.landscape_image_url) cliArgs.push("--landscape-image", a.landscape_image_url as string);
        if (a.square_image_url) cliArgs.push("--square-image", a.square_image_url as string);
        (a.headlines as string[] || []).forEach((h) => cliArgs.push("--headline", h));
        (a.descriptions as string[] || []).forEach((d) => cliArgs.push("--description", d));
        (a.geo_targets as string[] || []).forEach((g) => cliArgs.push("--geo-targets", g));
        return cliArgs;
      },
    },
    create_pmax_campaign: {
      script: "google_ads_create_pmax_campaign",
      platform: "google",
      argMapper: (a) => {
        const cliArgs: string[] = [
          "--campaign-name", a.campaign_name as string,
          "--daily-budget", String(a.daily_budget),
          "--business-name", a.business_name as string,
          "--final-url", a.final_url as string,
          "--long-headline", a.long_headline as string,
        ];
        if (a.landscape_image_url) cliArgs.push("--landscape-image-url", a.landscape_image_url as string);
        if (a.square_image_url) cliArgs.push("--square-image-url", a.square_image_url as string);
        if (a.logo_url) cliArgs.push("--logo-url", a.logo_url as string);
        if (a.target_cpa) cliArgs.push("--target-cpa", String(a.target_cpa));
        (a.headlines as string[] || []).forEach((h) => cliArgs.push("--headline", h));
        (a.descriptions as string[] || []).forEach((d) => cliArgs.push("--description", d));
        (a.geo_targets as string[] || []).forEach((g) => cliArgs.push("--geo-targets", g));
        return cliArgs;
      },
    },
    pause_campaign: {
      script: "pause_campaign",
      platform: "google",
      argMapper: (a) => ["--campaign-id", a.campaign_id as string],
    },
    update_campaign_budget: {
      script: "update_campaign_budget",
      platform: "google",
      argMapper: (a) => [
        "--campaign-id", a.campaign_id as string,
        "--budget", String(a.daily_budget),
      ],
    },

    // Performance
    get_performance: {
      script: "pull_google_ads_data",
      platform: "google",
      argMapper: (a) => {
        const cliArgs: string[] = [];
        if (a.campaign_id) cliArgs.push("--campaign-id", a.campaign_id as string);
        if (a.date_range) cliArgs.push("--date-range", a.date_range as string);
        return cliArgs;
      },
    },
    get_daily_spend: {
      script: "get_account_daily_spend",
      platform: "google",
      argMapper: (a) => {
        const cliArgs: string[] = [];
        if (a.days) cliArgs.push("--days", String(a.days));
        return cliArgs;
      },
    },

    // Keywords
    add_keywords: {
      script: "google_ads_add_keywords",
      platform: "google",
      argMapper: (a) => {
        const cliArgs: string[] = ["--ad-group-id", a.ad_group_id as string];
        (a.keywords as string[] || []).forEach((k) => cliArgs.push("--keyword", k));
        if (a.match_type) cliArgs.push("--match-type", a.match_type as string);
        return cliArgs;
      },
    },
    add_negative_keywords: {
      script: "google_ads_add_negative_keywords",
      platform: "google",
      argMapper: (a) => {
        const cliArgs: string[] = ["--campaign-id", a.campaign_id as string];
        (a.keywords as string[] || []).forEach((k) => cliArgs.push("--keyword", k));
        if (a.level) cliArgs.push("--level", a.level as string);
        return cliArgs;
      },
    },

    // Conversions
    create_conversion: {
      script: "google_ads_create_conversion",
      platform: "google",
      argMapper: (a) => {
        const cliArgs: string[] = ["--name", a.name as string];
        if (a.value) cliArgs.push("--value", String(a.value));
        if (a.category) cliArgs.push("--category", a.category as string);
        return cliArgs;
      },
    },
    list_conversions: {
      script: "google_ads_list_conversions",
      platform: "google",
      argMapper: () => [],
    },
    diagnose_tracking: {
      script: "diagnose_conversion_tracking",
      argMapper: (a) => ["--url", a.url as string],
    },

    // Creative generation
    generate_image: {
      script: "generate_image",
      argMapper: (a) => {
        const cliArgs: string[] = ["--prompt", a.prompt as string];
        if (a.size) cliArgs.push("--size", a.size as string);
        if (a.provider) cliArgs.push("--provider", a.provider as string);
        if (a.name) cliArgs.push("--name", a.name as string);
        return cliArgs;
      },
    },
    generate_video: {
      script: "generate_video_ad",
      argMapper: (a) => {
        const cliArgs: string[] = [
          "--product", a.product_name as string,
          "--benefit", a.key_benefit as string,
        ];
        if (a.concept) cliArgs.push("--concept", a.concept as string);
        if (a.target_audience) cliArgs.push("--audience", a.target_audience as string);
        if (a.duration) cliArgs.push("--duration", String(a.duration));
        if (a.provider) cliArgs.push("--provider", a.provider as string);
        return cliArgs;
      },
    },

    // Meta
    create_meta_campaign: {
      script: "meta_ads_create_campaign",
      platform: "meta",
      argMapper: (a) => [
        "--name", a.name as string,
        "--objective", a.objective as string,
        "--daily-budget", String(a.daily_budget),
      ],
    },

    // LinkedIn
    create_linkedin_campaign: {
      script: "linkedin_ads_create_campaign_complete",
      platform: "linkedin",
      argMapper: (a) => {
        const cliArgs: string[] = [
          "--name", a.name as string,
          "--objective", a.objective as string,
          "--daily-budget", String(a.daily_budget),
        ];
        (a.target_company_sizes as string[] || []).forEach((s) => cliArgs.push("--company-size", s));
        (a.target_industries as string[] || []).forEach((i) => cliArgs.push("--industry", i));
        (a.target_job_functions as string[] || []).forEach((j) => cliArgs.push("--job-function", j));
        return cliArgs;
      },
    },

    // Reddit
    create_reddit_campaign: {
      script: "reddit_ads_create_campaign",
      platform: "reddit",
      argMapper: (a) => {
        const cliArgs: string[] = [
          "--name", a.name as string,
          "--objective", a.objective as string,
          "--daily-budget", String(a.daily_budget),
        ];
        (a.subreddits as string[] || []).forEach((s) => cliArgs.push("--subreddit", s));
        (a.interests as string[] || []).forEach((i) => cliArgs.push("--interest", i));
        return cliArgs;
      },
    },

    // Utility
    list_ad_accounts: {
      script: "google_ads_list_customers",
      platform: "google",
      argMapper: () => [],
    },
    upload_image: {
      script: "google_ads_upload_image_asset",
      platform: "google",
      argMapper: (a) => [
        "--image-url", a.image_url as string,
        "--asset-name", a.asset_name as string,
      ],
    },
    run_tool: {
      script: args.script_name as string,
      platform: (args.platform as string) || undefined,
      argMapper: (a) => (a.args as string[]) || [],
    },
  };

  const mapping = toolMappings[name];
  if (!mapping) {
    throw new Error(`Unknown tool: ${name}`);
  }

  const scriptArgs = mapping.argMapper ? mapping.argMapper(args) : [];
  
  return callSynterAPI("tools/run", {
    script_name: mapping.script,
    args: scriptArgs,
    platform: typeof mapping.platform === "function" 
      ? mapping.platform 
      : mapping.platform || (args.platform as string),
  });
}

src/index.ts:311-335 (schema)

Tool registration and inputSchema definition for 'add_keywords'. Defines the tool name, description, annotations (destructiveHint), and input parameters: ad_group_id (required string), keywords (required array of strings), and match_type (optional enum: EXACT, PHRASE, BROAD).

{
  name: "add_keywords",
  description: "Add keywords to a Google Ads campaign or ad group.",
  annotations: { destructiveHint: true },
  inputSchema: {
    type: "object" as const,
    properties: {
      ad_group_id: {
        type: "string",
        description: "Ad group ID to add keywords to",
      },
      keywords: {
        type: "array",
        items: { type: "string" },
        description: "Keywords to add",
      },
      match_type: {
        type: "string",
        enum: ["EXACT", "PHRASE", "BROAD"],
        description: "Keyword match type (default: PHRASE)",
      },
    },
    required: ["ad_group_id", "keywords"],
  },
},

src/index.ts:666-693 (helper)

The callSynterAPI helper function that makes HTTP POST requests to the Synter API endpoint. Used by handleTool to execute the script with the mapped arguments. Handles authentication with SYNTER_API_KEY and error responses.

async function callSynterAPI(
  endpoint: string,
  body: Record<string, unknown>
): Promise<Record<string, unknown>> {
  if (!SYNTER_API_KEY) {
    throw new Error(
      "SYNTER_API_KEY not set. Get your API key at https://syntermedia.ai/developer"
    );
  }

  const response = await fetch(`${SYNTER_API_URL}/api/v1/${endpoint}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${SYNTER_API_KEY}`,
    },
    body: JSON.stringify(body),
  });

  const data = await response.json() as Record<string, unknown>;

  if (!response.ok) {
    const errorMsg = (data.error as string) || (data.message as string) || `API error: ${response.status}`;
    throw new Error(errorMsg);
  }

  return data;
}

src/index.ts:981-1006 (registration)

MCP server request handler for CallToolRequestSchema that invokes handleTool when a tool is called. This is where the 'add_keywords' tool execution is triggered when requested by an MCP client.

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    const result = await handleTool(name, (args || {}) as ToolArgs);

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  } catch (error) {
    return {
      content: [
        {
          type: "text",
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
        },
      ],
      isError: true,
    };
  }
});

Synter MCP Server

add_keywords

Instructions

Input Schema

Implementation Reference

Other Tools

Latest Blog Posts

MCP directory API