{ "openapi": "3.1.0", "info": { "title": "Google Ads MCP Server", "description": "Google Ads campaign management with GAQL query support", "version": "1.0.0", "contact": { "name": "Hopkin", "url": "https://hopkin.ai" } }, "servers": [ { "url": "https://google.mcp.hopkin.ai", "description": "Production MCP endpoint" } ], "paths": { "/tools": { "get": { "operationId": "listTools", "summary": "List available tools", "description": "Returns all tools registered on this server with their names, descriptions, and input schemas.", "tags": [ "discovery" ], "responses": { "200": { "description": "Tool list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ToolList" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } } } } }, "/tools/google_ads_get_account_summary": { "post": { "operationId": "google_ads_get_account_summary", "summary": "Get Google Ads Account Summary", "description": "Standardized account-level performance summary for cross-platform comparison. Returns normalized metrics identical to meta_ads_get_account_summary, with per-conversion-action breakdown. Preferred over insights or performance report for quick account overviews. Always fetches fresh data.", "tags": [ "account-summary" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "last-30-days-summary": { "summary": "Last 30 days summary", "value": { "customer_id": "1234567890", "reason": "Quick performance overview" } }, "last-7-days": { "summary": "Last 7 days", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Weekly check-in" } }, "with-mcc": { "summary": "With MCC", "value": { "customer_id": "1234567890", "login_customer_id": "9876543210", "date_preset": "LAST_30_DAYS", "reason": "Managed account overview" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_activities": { "post": { "operationId": "google_ads_get_activities", "summary": "Get Google Ads Activities", "description": "Retrieve change history for a Google Ads account. Always fetches fresh data. Only changes within the past 30 days are available (API limit), and changes may take up to 3 minutes to appear. For CAMPAIGN_CRITERION events, use the description field as the definitive interpretation when present.", "tags": [ "activities" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date in YYYY-MM-DD format. Defaults to 7 days ago. Must be within the past 30 days." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date in YYYY-MM-DD format. Defaults to today." }, "resource_type": { "type": "string", "enum": [ "AD", "AD_GROUP", "AD_GROUP_AD", "AD_GROUP_CRITERION", "CAMPAIGN", "CAMPAIGN_BUDGET", "CAMPAIGN_CRITERION", "ASSET", "ASSET_SET" ], "description": "Filter to a specific resource type: AD, AD_GROUP, AD_GROUP_AD, AD_GROUP_CRITERION, CAMPAIGN, CAMPAIGN_BUDGET, CAMPAIGN_CRITERION, ASSET, ASSET_SET" }, "asset_ids": { "type": "array", "items": { "type": "string" }, "description": "Filter to specific asset IDs (numeric). Automatically sets resource_type to ASSET." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Maximum number of activities to return (1-1000, default 50)" }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "recent-account-activity": { "summary": "Recent account activity", "value": { "customer_id": "1234567890", "reason": "Review recent account changes" } }, "campaign-changes-only": { "summary": "Campaign changes only", "value": { "customer_id": "1234567890", "resource_type": "CAMPAIGN", "reason": "See recent campaign edits" } }, "custom-date-range": { "summary": "Custom date range", "value": { "customer_id": "1234567890", "start_date": "2026-02-01", "end_date": "2026-02-28", "reason": "February activity audit" } }, "with-mcc-login": { "summary": "With MCC login", "value": { "customer_id": "1234567890", "login_customer_id": "9876543210", "reason": "Review changes on managed account" } }, "specific-asset-activity": { "summary": "Specific asset activity", "value": { "customer_id": "1234567890", "asset_ids": [ "123456789", "987654321" ], "reason": "Check recent changes to specific assets" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_accounts": { "post": { "operationId": "google_ads_list_accounts", "summary": "List Google Ads Accounts", "description": "List Google Ads accounts accessible by the user, including MCC child accounts. When calling other tools for MCC child accounts, you MUST pass login_customer_id with the parent MCC Customer ID. Results are cached; pass refresh=true for latest data. To list only children of a specific MCC, use google_ads_list_mcc_child_accounts instead.", "tags": [ "accounts" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "Get a specific account by Customer ID. When provided, returns only that account and ignores other filters/pagination." }, "customer_ids": { "type": "array", "items": { "type": "string", "pattern": "^[\\d-]+$" }, "minItems": 1, "maxItems": 50, "description": "Get multiple accounts by Customer ID. Mutually exclusive with customer_id. When provided, ignores other filters/pagination." }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "search": { "type": "string", "minLength": 1, "description": "Search accounts by name (case-insensitive partial match)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of accounts per page (default: 20, max: 100)" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "reason": "List all ad accounts" } }, "get-by-id": { "summary": "Get by ID", "value": { "customer_id": "1234567890", "reason": "Get account details" } }, "search-by-name": { "summary": "Search by name", "value": { "search": "marketing", "reason": "Find marketing accounts" } }, "get-multiple-by-id": { "summary": "Get multiple by ID", "value": { "customer_ids": [ "1234567890", "0987654321" ], "reason": "Get details for specific accounts" } }, "force-refresh": { "summary": "Force refresh", "value": { "refresh": true, "reason": "Get fresh data" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_mcc_child_accounts": { "post": { "operationId": "google_ads_list_mcc_child_accounts", "summary": "List MCC Child Accounts", "description": "List child accounts under a specific MCC (Manager) account. When calling other tools for these child accounts, you MUST pass login_customer_id with the MCC Customer ID. For all accessible accounts regardless of hierarchy, use google_ads_list_accounts instead.", "tags": [ "mcc-child-accounts" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mcc_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The MCC (Manager) Customer ID whose child accounts to list (10 digits, dashes accepted)" }, "search": { "type": "string", "minLength": 1, "description": "Search child accounts by name or customer ID (case-insensitive partial match)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of accounts per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "mcc_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-children": { "summary": "List children", "value": { "mcc_id": "1234567890", "reason": "List MCC child accounts" } }, "search-children": { "summary": "Search children", "value": { "mcc_id": "1234567890", "search": "marketing", "reason": "Find child accounts" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_ad_groups": { "post": { "operationId": "google_ads_list_ad_groups", "summary": "List Google Ads Ad Groups", "description": "List ad groups for a Google Ads account. Supports filtering by campaign, status, search, and pagination. Results are cached; pass refresh=true for latest data. Set include_audience_criteria=true to include ad-group-level audience targeting (USER_LIST, USER_INTEREST) with bid modifiers.", "tags": [ "ad-groups" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter by campaign ID (optional)" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Get a specific ad group by ID. When provided, returns only that ad group and ignores other filters/pagination." }, "ad_group_ids": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 50, "description": "Get multiple ad groups by ID. Mutually exclusive with ad_group_id. When provided, ignores other filters/pagination." }, "search": { "type": "string", "minLength": 1, "description": "Search ad groups by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ENABLED", "PAUSED", "REMOVED" ] }, "description": "Filter by ad group status: ENABLED, PAUSED, REMOVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of ad groups per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "include_audience_criteria": { "type": "boolean", "default": false, "description": "Include ad-group-level audience criteria (USER_LIST, USER_INTEREST) with bid modifiers. Useful for auditing RLSA audiences and observation/targeting mode." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "customer_id": "1234567890", "reason": "List ad groups" } }, "filter-by-campaign": { "summary": "Filter by campaign", "value": { "customer_id": "1234567890", "campaign_id": "9876543210", "reason": "List ad groups in campaign" } }, "get-by-id": { "summary": "Get by ID", "value": { "customer_id": "1234567890", "ad_group_id": "5555555555", "reason": "Get ad group details" } }, "search": { "summary": "Search", "value": { "customer_id": "1234567890", "search": "brand", "reason": "Find brand ad groups" } }, "get-multiple-by-id": { "summary": "Get multiple by ID", "value": { "customer_id": "1234567890", "ad_group_ids": [ "111", "222", "333" ], "reason": "Get details for specific ad groups" } }, "filter-by-status": { "summary": "Filter by status", "value": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled ad groups" } }, "with-audiences": { "summary": "With audiences", "value": { "customer_id": "1234567890", "campaign_id": "9876543210", "include_audience_criteria": true, "reason": "Audit RLSA audiences" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_preview_ads": { "post": { "operationId": "google_ads_preview_ads", "summary": "Preview Google Ads", "description": "Interactive UI for displaying Google ad previews with creative content and metrics", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads customer ID" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC manager account ID if needed" }, "ads": { "type": "array", "items": { "type": "object", "properties": { "ad_id": { "type": "string", "pattern": "^\\d+$", "description": "The Google ad ID" }, "metrics": { "type": "object", "additionalProperties": { "type": [ "string", "number" ] }, "description": "Metric name-value pairs to display" } }, "required": [ "ad_id" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20, "description": "Ads to preview (1-20)" }, "metric_labels": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Display labels for metric keys" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "ads", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "single-ad": { "summary": "Single ad", "value": { "customer_id": "1234567890", "ads": [ { "ad_id": "12345" } ], "reason": "Preview ad creative" } }, "with-metrics": { "summary": "With metrics", "value": { "customer_id": "1234567890", "ads": [ { "ad_id": "12345", "metrics": { "spend": "150.00", "ctr": "2.5%" } } ], "metric_labels": { "spend": "Spend", "ctr": "Click Rate" }, "reason": "Preview ad with performance metrics" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } }, "x-mcp-tool-type": "app" } }, "/tools/google_ads_list_ads": { "post": { "operationId": "google_ads_list_ads", "summary": "List Google Ads", "description": "List ads for a Google Ads account. Supports filtering by ad group, status, search, and pagination. Results are cached; pass refresh=true for latest data.", "tags": [ "ads" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter by ad group ID (optional)" }, "ad_id": { "type": "string", "pattern": "^\\d+$", "description": "Get a specific ad by ID. When provided, returns only that ad and ignores other filters/pagination." }, "ad_ids": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 50, "description": "Get multiple ads by ID. Mutually exclusive with ad_id. When provided, ignores other filters/pagination." }, "search": { "type": "string", "minLength": 1, "description": "Search ads by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ENABLED", "PAUSED", "REMOVED" ] }, "description": "Filter by ad status: ENABLED, PAUSED, REMOVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of ads per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "customer_id": "1234567890", "reason": "List ads" } }, "filter-by-ad-group": { "summary": "Filter by ad group", "value": { "customer_id": "1234567890", "ad_group_id": "5555555555", "reason": "List ads in ad group" } }, "get-by-id": { "summary": "Get by ID", "value": { "customer_id": "1234567890", "ad_id": "7777777777", "reason": "Get ad details" } }, "search": { "summary": "Search", "value": { "customer_id": "1234567890", "search": "promo", "reason": "Find promo ads" } }, "get-multiple-by-id": { "summary": "Get multiple by ID", "value": { "customer_id": "1234567890", "ad_ids": [ "111", "222", "333" ], "reason": "Get details for specific ads" } }, "filter-by-status": { "summary": "Filter by status", "value": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled ads" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_audiences": { "post": { "operationId": "google_ads_list_audiences", "summary": "List Google Ads Audiences", "description": "List audience lists (user lists) for a Google Ads account. Returns Customer Match lists, remarketing audiences, rule-based audiences, similar audiences, and lookalike segments. Shows list names, types, sizes (for Search and Display), membership status, and match rates. Supports filtering by type and membership status, plus name search.", "tags": [ "audiences" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "type": { "type": "array", "items": { "type": "string", "enum": [ "CRM_BASED", "REMARKETING", "LOGICAL_USER_LIST", "EXTERNAL_REMARKETING", "RULE_BASED", "SIMILAR", "LOOKALIKE" ] }, "description": "Filter by audience type(s). Examples: CRM_BASED, REMARKETING, RULE_BASED, LOOKALIKE" }, "membership_status": { "type": "string", "enum": [ "OPEN", "CLOSED" ], "description": "Filter by membership status: OPEN (accepting new members) or CLOSED" }, "search": { "type": "string", "description": "Case-insensitive search filter applied to audience list names" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of lists per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "all-audiences": { "summary": "All audiences", "value": { "customer_id": "1234567890", "reason": "Audit all audience lists on the account" } }, "customer-match-only": { "summary": "Customer Match only", "value": { "customer_id": "1234567890", "type": [ "CRM_BASED" ], "reason": "View Customer Match lists and match rates" } }, "search-by-name": { "summary": "Search by name", "value": { "customer_id": "1234567890", "search": "remarketing", "reason": "Find remarketing audiences by name" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_check_auth_status": { "post": { "operationId": "google_ads_check_auth_status", "summary": "Check Google Ads Auth Status", "description": "Troubleshoot authentication issues and get user profile info. Only use when another tool fails with a permission or authentication error — do NOT call proactively.", "tags": [ "auth" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "check-auth": { "summary": "Check auth", "value": { "reason": "Another tool returned an auth error, checking account connection status" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_auto_applied_recommendations": { "post": { "operationId": "google_ads_get_auto_applied_recommendations", "summary": "Check Google Ads Auto-Applied Recommendations", "description": "Check which Google Ads recommendation types are set to auto-apply for an account. Auto-applied recommendations can automatically change bids, budgets, keywords, and campaign structure without manual review. Essential for account audits.", "tags": [ "auto-applied-recommendations" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "check-auto-applied": { "summary": "Check auto-applied", "value": { "customer_id": "1234567890", "reason": "Audit auto-applied recommendation settings" } }, "mcc-account": { "summary": "MCC account", "value": { "customer_id": "1234567890", "login_customer_id": "9876543210", "reason": "Check auto-applied for managed account" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_campaigns": { "post": { "operationId": "google_ads_list_campaigns", "summary": "List Google Ads Campaigns", "description": "List campaigns for a Google Ads account. Supports status filtering, search, and pagination. Results are cached; pass refresh=true for latest data. Use include_criteria to control audience/schedule detail: \"none\" (fastest), \"summary\" (default, capped), or \"full\" (uncapped, requires campaign_id/campaign_ids).", "tags": [ "campaigns" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Get a specific campaign by ID. When provided, returns only that campaign and ignores other filters/pagination." }, "campaign_ids": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 50, "description": "Get multiple campaigns by ID. Mutually exclusive with campaign_id. When provided, ignores other filters/pagination." }, "search": { "type": "string", "minLength": 1, "description": "Search campaigns by name (case-insensitive partial match)" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ENABLED", "PAUSED", "REMOVED" ] }, "description": "Filter by campaign status: ENABLED, PAUSED, REMOVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of campaigns per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "refresh": { "type": "boolean", "default": false, "description": "Force fresh data from Google Ads API instead of using cache. Defaults to false (cache-first). Only set to true when you need real-time data." }, "include_criteria": { "type": "string", "enum": [ "none", "summary", "full" ], "default": "summary", "description": "Controls campaign criteria detail level. \"none\" omits criteria (fastest). \"summary\" (default) returns capped criteria with total counts. \"full\" returns all criteria uncapped — requires campaign_id or campaign_ids (max 10)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "customer_id": "1234567890", "reason": "List campaigns" } }, "filter-by-status": { "summary": "Filter by status", "value": { "customer_id": "1234567890", "status": [ "ENABLED" ], "reason": "List enabled campaigns" } }, "get-by-id": { "summary": "Get by ID", "value": { "customer_id": "1234567890", "campaign_id": "9876543210", "reason": "Get campaign details" } }, "search": { "summary": "Search", "value": { "customer_id": "1234567890", "search": "brand", "reason": "Find brand campaigns" } }, "get-multiple-by-id": { "summary": "Get multiple by ID", "value": { "customer_id": "1234567890", "campaign_ids": [ "111", "222", "333" ], "reason": "Get details for specific campaigns" } }, "mcc-child": { "summary": "MCC child", "value": { "customer_id": "1234567890", "login_customer_id": "9999999999", "reason": "List campaigns for MCC child" } }, "full-criteria-for-campaign": { "summary": "Full criteria for campaign", "value": { "customer_id": "1234567890", "campaign_id": "9876543210", "include_criteria": "full", "reason": "Get all audiences for campaign" } }, "fast-listing-no-criteria": { "summary": "Fast listing (no criteria)", "value": { "customer_id": "1234567890", "include_criteria": "none", "reason": "Quick campaign overview" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_render_chart": { "post": { "operationId": "google_ads_render_chart", "summary": "Render Chart", "description": "Interactive UI for rendering data visualization charts", "tags": [ "chart" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Brief explanation of why you are rendering this chart" }, "chart": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "bar" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": [ "number", "null" ] } } }, "required": [ "label", "values" ], "additionalProperties": false } }, "metric": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" }, "tickFormat": { "type": "string" }, "labelFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "format": { "type": "string" }, "suffix": { "type": "string" } }, "required": [ "field" ], "additionalProperties": false } } }, "required": [ "field", "label" ], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" }, "tickFormat": { "type": "string" }, "labelFields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "format": { "type": "string" }, "suffix": { "type": "string" } }, "required": [ "field" ], "additionalProperties": false } } }, "required": [ "field", "label" ], "additionalProperties": false } } ] }, "orientation": { "type": "string", "enum": [ "horizontal", "vertical" ], "default": "horizontal" }, "sort": { "type": "string", "enum": [ "asc", "desc", "none" ], "default": "desc" }, "colorBy": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "threshold" }, "field": { "type": "string" }, "threshold": { "type": "number" }, "sentiment": { "type": "string", "enum": [ "above-positive", "above-negative" ], "default": "above-positive" } }, "required": [ "type", "field", "threshold" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "continuous" }, "field": { "type": "string" }, "scheme": { "type": "string" }, "reverse": { "type": "boolean", "default": false }, "muteZero": { "type": "boolean", "default": false }, "label": { "type": "string" } }, "required": [ "type", "field", "scheme" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "categorical" } }, "required": [ "type" ], "additionalProperties": false } ] }, "referenceLines": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "label": { "type": "string" }, "dash": { "type": "string", "enum": [ "solid", "dashed" ], "default": "dashed" } }, "required": [ "value" ], "additionalProperties": false } }, "table": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "columns" ], "additionalProperties": false }, "panelWidth": { "type": "number" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 400 } }, "required": [ "type", "data", "metric" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "scatter" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "label", "values" ], "additionalProperties": false } }, "x": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "scale": { "type": "string", "enum": [ "linear", "log" ], "default": "linear" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false }, "y": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "scale": { "type": "string", "enum": [ "linear", "log" ], "default": "linear" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false }, "size": { "type": "object", "properties": { "field": { "type": "string" }, "range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "default": [ 3, 20 ] } }, "required": [ "field" ], "additionalProperties": false }, "color": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "continuous" }, "field": { "type": "string" }, "scheme": { "type": "string" }, "reverse": { "type": "boolean", "default": false } }, "required": [ "type", "field", "scheme" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "threshold" }, "field": { "type": "string" }, "threshold": { "type": "number" }, "sentiment": { "type": "string", "enum": [ "above-positive", "above-negative" ], "default": "above-positive" } }, "required": [ "type", "field", "threshold" ], "additionalProperties": false } ] }, "referenceLines": { "type": "object", "properties": { "medianX": { "type": "boolean", "default": false }, "medianY": { "type": "boolean", "default": false }, "targets": { "type": "array", "items": { "type": "object", "properties": { "slope": { "type": "number" }, "label": { "type": "string" } }, "required": [ "slope", "label" ], "additionalProperties": false } }, "regression": { "type": "boolean", "default": false } }, "additionalProperties": false }, "table": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "columns" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 450 } }, "required": [ "type", "data", "x", "y" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "timeseries" }, "data": { "type": "object", "properties": { "current": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } }, "previous": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } }, "projection": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "values": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "date", "values" ], "additionalProperties": false } } }, "required": [ "current" ], "additionalProperties": false }, "primaryAxis": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "mark": { "type": "string", "enum": [ "bar", "area", "line" ] }, "groupBars": { "type": "boolean" } }, "required": [ "field", "label", "mark" ], "additionalProperties": false }, "secondaryAxis": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "dash": { "type": "string", "enum": [ "solid", "dashed" ], "default": "solid" } }, "required": [ "field", "label" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 400 } }, "required": [ "type", "data", "primaryAxis" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "funnel" }, "data": { "type": "object", "properties": { "stages": { "type": "array", "items": { "type": "string" } }, "volume": { "type": "array", "items": { "type": "number" } }, "costPer": { "type": "array", "items": { "type": "number" } } }, "required": [ "stages", "volume" ], "additionalProperties": false }, "showConversionRates": { "type": "boolean", "default": true }, "showCostPer": { "type": "boolean", "default": true }, "colorScheme": { "type": "string", "default": "Blues" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 350 } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "waterfall" }, "data": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "number" }, "colorValue": { "type": "number" } }, "required": [ "label", "value", "colorValue" ], "additionalProperties": false } }, "colorScheme": { "type": "string", "default": "RdYlGn" }, "colorLabel": { "type": "string", "default": "CPA ($)" }, "valueLabel": { "type": "string", "default": "Cumulative Spend ($)" }, "width": { "type": "number", "default": 700 }, "height": { "type": "number" } }, "required": [ "type", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choropleth" }, "data": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string" }, "value": { "type": "number" }, "meta": { "type": "object", "additionalProperties": { "type": [ "string", "number", "null" ] } } }, "required": [ "state", "value" ], "additionalProperties": false } }, "valueLabel": { "type": "string" }, "colorScheme": { "type": "string", "default": "YlOrRd" }, "colorType": { "type": "string", "enum": [ "quantize", "linear", "threshold" ], "default": "quantize" }, "reverse": { "type": "boolean", "default": false }, "tip": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "label": { "type": "string" }, "format": { "type": "string" } }, "required": [ "field", "label" ], "additionalProperties": false } } }, "required": [ "fields" ], "additionalProperties": false }, "width": { "type": "number", "default": 700 }, "height": { "type": "number", "default": 450 } }, "required": [ "type", "data", "valueLabel" ], "additionalProperties": false } ] } }, "required": [ "reason", "chart" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } }, "x-mcp-tool-type": "app", "x-mcp-chart-types": [ "bar", "scatter", "timeseries", "funnel", "waterfall", "choropleth" ] } }, "/tools/google_ads_get_conversion_actions": { "post": { "operationId": "google_ads_get_conversion_actions", "summary": "List Google Ads Conversion Actions", "description": "List conversion actions configured for a Google Ads account. Use this to understand which conversions are tracked before querying performance reports or insights with conversion segments.", "tags": [ "conversion-actions" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1, "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "minLength": 1, "description": "MCC (Manager) Customer ID; required for managed accounts" }, "status": { "type": "string", "enum": [ "ENABLED", "REMOVED", "HIDDEN" ], "description": "Filter by status (default: returns all non-REMOVED). ENABLED, REMOVED, HIDDEN" }, "limit": { "type": "number", "minimum": 1, "maximum": 500, "default": 100, "description": "Maximum number of conversion actions to return (default: 100, max: 500)" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "list-all": { "summary": "List all", "value": { "customer_id": "1234567890", "reason": "See configured conversion actions" } }, "enabled-only": { "summary": "Enabled only", "value": { "customer_id": "1234567890", "status": "ENABLED", "reason": "Active conversion actions" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_developer_feedback": { "post": { "operationId": "google_ads_developer_feedback", "summary": "Submit Developer Feedback", "description": "Submit feedback about missing tools, needed improvements, bugs, or workflow gaps in the MCP toolset. Not for user-facing issues (auth errors, API errors).", "tags": [ "feedback" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedback_type": { "type": "string", "enum": [ "new_tool", "improvement", "bug", "workflow_gap" ], "description": "Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow)" }, "title": { "type": "string", "minLength": 5, "maxLength": 200, "description": "Concise title summarizing the feedback" }, "description": { "type": "string", "minLength": 20, "maxLength": 2000, "description": "What is needed and why" }, "current_workaround": { "type": "string", "maxLength": 1000, "description": "Current workaround, if any" }, "priority": { "type": "string", "enum": [ "low", "medium", "high" ], "default": "medium", "description": "Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue)" }, "interface": { "type": "string", "enum": [ "MCP", "CLI" ], "default": "MCP", "description": "Interface the feedback originated from: MCP (default) or CLI" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "feedback_type", "title", "description", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "missing-tool": { "summary": "Missing tool", "value": { "feedback_type": "new_tool", "title": "Bulk campaign status toggle", "description": "Need to pause/enable multiple campaigns at once", "priority": "high", "reason": "User asked to pause 12 campaigns individually" } }, "workflow-gap": { "summary": "Workflow gap", "value": { "feedback_type": "workflow_gap", "title": "Campaign cloning with ad groups", "description": "No way to duplicate a campaign including ad groups and ads", "current_workaround": "Read and recreate each level one by one", "reason": "User wanted to duplicate campaign structure" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_geo_performance": { "post": { "operationId": "google_ads_get_geo_performance", "summary": "Get Google Ads Geographic Performance", "description": "Get geographic performance data from the geographic_view resource. Only ONE geo level per query. Returns both AREA_OF_INTEREST and LOCATION_OF_PRESENCE location types with auto-resolved location names. Includes a parallel conversion action breakdown. Location names are resolved automatically from criterion IDs.", "tags": [ "geo-performance" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "geo_level": { "type": "string", "enum": [ "country", "geo_target_city", "geo_target_region", "geo_target_state", "geo_target_metro", "geo_target_province", "geo_target_county", "geo_target_district", "geo_target_most_specific_location", "geo_target_postal_code", "geo_target_airport", "geo_target_canton" ], "default": "country", "description": "Geographic granularity. \"country\" uses geographic_view.country_criterion_id; others add a segments.geo_target_* drill-down. Only one geo level per query." }, "level": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP" ], "default": "CAMPAIGN", "description": "Entity breakdown level" }, "segments": { "type": "array", "items": { "type": "string", "enum": [ "date", "device", "ad_network_type" ] }, "description": "Additional non-geo segments: date, device, ad_network_type" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "limit": { "type": "number", "minimum": 1, "maximum": 200, "default": 50, "description": "Max rows returned (default 50, max 200)" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "country-performance": { "summary": "Country performance", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "geo_level": "country", "reason": "Compare spend by country" } }, "city-level-breakdown": { "summary": "City-level breakdown", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "geo_level": "geo_target_city", "level": "CAMPAIGN", "reason": "City performance analysis" } }, "country-by-campaign": { "summary": "Country by campaign", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "geo_level": "country", "level": "CAMPAIGN", "segments": [ "date" ], "reason": "Daily country trends per campaign" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_insights": { "post": { "operationId": "google_ads_get_insights", "summary": "Get Google Ads Insights", "description": "Retrieve performance metrics using GAQL with full control over metrics, segments, levels, and date ranges. Always fetches fresh data. Supports device breakdowns (segments: ['device']), ad_network_type channel analysis (Performance Max by SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER, etc.), and search impression share diagnostics. For standard analysis, prefer google_ads_get_performance_report; use this only for custom metric selection, search impression share diagnostics, ad_network_type channel breakdowns, or segment combinations not available in the performance report. For geographic data, use google_ads_get_geo_performance instead. Conversion action segments automatically remove incompatible cost-based metrics. Budget-lost impression share variants are campaign-level only.", "tags": [ "insights" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "level": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP", "AD" ], "default": "ACCOUNT", "description": "Report level (default: ACCOUNT): ACCOUNT, CAMPAIGN, AD_GROUP, AD" }, "metrics": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Metrics to retrieve (defaults to standard set)" }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Segments to break down by (e.g., date, device, ad_network_type). Use ad_network_type to see which channel delivered traffic (SEARCH, YOUTUBE_WATCH, DISPLAY, DISCOVER, etc.) — essential for Performance Max analysis." }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "all-conversions-by-action": { "summary": "All conversions by action", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "metrics": [ "all_conversions", "all_conversions_value", "value_per_all_conversions" ], "segments": [ "conversion_action_name" ], "reason": "All conversions breakdown by action" } }, "search-impression-share": { "summary": "Search impression share", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "level": "CAMPAIGN", "metrics": [ "search_impression_share", "search_top_impression_share", "search_absolute_top_impression_share", "search_budget_lost_impression_share", "search_rank_lost_impression_share" ], "reason": "Search IS diagnostics" } }, "device-breakdown-with-custom-metrics": { "summary": "Device breakdown with custom metrics", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "level": "CAMPAIGN", "segments": [ "device" ], "metrics": [ "impressions", "clicks", "cost_micros", "conversions", "view_through_conversions" ], "reason": "Device breakdown with view-through conversions" } }, "pmax-channel-breakdown": { "summary": "PMax channel breakdown", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "level": "CAMPAIGN", "segments": [ "ad_network_type" ], "reason": "PMax channel-level performance breakdown" } } } } } }, "responses": { "200": { "description": "JSON report data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_generate_keyword_ideas": { "post": { "operationId": "google_ads_generate_keyword_ideas", "summary": "Generate Google Ads Keyword Ideas", "description": "Generate keyword suggestions from seed keywords and/or a URL. Returns keyword ideas with average monthly searches, competition level, and estimated bid ranges. Supports pagination for large result sets. Examples: seed with [\"running shoes\", \"athletic footwear\"] for shoe campaigns, or provide a competitor URL to discover relevant keywords. Use include_monthly_volumes=true for seasonal trend data.", "tags": [ "generate-keyword-ideas" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Seed keywords to generate ideas from (max 20). At least one of keywords or url must be provided." }, "url": { "type": "string", "format": "uri", "description": "Seed URL to generate keyword ideas from. At least one of keywords or url must be provided." }, "language": { "type": "string", "minLength": 2, "maxLength": 5, "default": "en", "description": "ISO 639-1 language code (e.g., \"en\", \"es\"). Default: \"en\"." }, "geo_targets": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "default": [ "US" ], "description": "ISO 3166-1 alpha-2 country codes (e.g., [\"US\", \"GB\"]). Default: [\"US\"]." }, "network": { "type": "string", "enum": [ "GOOGLE_SEARCH", "GOOGLE_SEARCH_AND_PARTNERS" ], "default": "GOOGLE_SEARCH", "description": "Keyword plan network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS" }, "include_adult_keywords": { "type": "boolean", "default": false, "description": "Whether to include adult keyword ideas. Default: false." }, "include_monthly_volumes": { "type": "boolean", "default": false, "description": "When true, includes per-month search volume history for each keyword. Default: false." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Maximum keyword ideas to return per page (1-1000, default 50)" }, "cursor": { "type": "string", "description": "Opaque pagination cursor from a previous response. Do not construct manually." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "from-seed-keywords": { "summary": "From seed keywords", "value": { "customer_id": "1234567890", "keywords": [ "running shoes", "athletic footwear" ], "reason": "Keyword research for new campaign" } }, "from-url": { "summary": "From URL", "value": { "customer_id": "1234567890", "url": "https://example.com/products/shoes", "reason": "Find keywords from competitor page" } }, "with-monthly-volumes": { "summary": "With monthly volumes", "value": { "customer_id": "1234567890", "keywords": [ "yoga mat" ], "include_monthly_volumes": true, "geo_targets": [ "US", "GB" ], "reason": "Seasonal trend analysis" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_keyword_historical_metrics": { "post": { "operationId": "google_ads_get_keyword_historical_metrics", "summary": "Get Google Ads Keyword Historical Metrics", "description": "Get historical search metrics for specific keywords — average monthly searches, competition level, and bid estimates. Unlike keyword ideas, this takes exact keywords you already have and returns their metrics. Use include_monthly_volumes=true for month-by-month search volume trends. Examples: check volume for [\"running shoes\", \"trail running shoes\"] before adding to campaigns, or validate keywords from external research.", "tags": [ "keyword-historical-metrics" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 200, "description": "Keywords to get historical metrics for (1-200 keywords)" }, "language": { "type": "string", "pattern": "^[a-z]{2}$", "description": "ISO 639-1 language code (e.g. \"en\", \"es\"). Maps internally to languageConstants resource name." }, "geo_targets": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "ISO 3166-1 alpha-2 country codes (e.g. [\"US\", \"GB\"]). Maps internally to geoTargetConstants." }, "network": { "type": "string", "enum": [ "GOOGLE_SEARCH", "GOOGLE_SEARCH_AND_PARTNERS" ], "default": "GOOGLE_SEARCH", "description": "Network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS" }, "include_monthly_volumes": { "type": "boolean", "default": false, "description": "When true, includes month-by-month search volume data. Default: false." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "keywords", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "basic-metrics": { "summary": "Basic metrics", "value": { "customer_id": "1234567890", "keywords": [ "running shoes", "trail running shoes" ], "reason": "Check keyword search volume" } }, "with-geo-targeting": { "summary": "With geo targeting", "value": { "customer_id": "1234567890", "keywords": [ "yoga classes" ], "geo_targets": [ "US" ], "language": "en", "reason": "Market sizing for US" } }, "monthly-trends": { "summary": "Monthly trends", "value": { "customer_id": "1234567890", "keywords": [ "winter coats" ], "include_monthly_volumes": true, "reason": "Analyze seasonal patterns" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_generate_keyword_forecast_metrics": { "post": { "operationId": "google_ads_generate_keyword_forecast_metrics", "summary": "Generate Google Ads Keyword Forecast Metrics", "description": "Forecast campaign performance for a set of keywords with budget and bidding config. Returns projected impressions, clicks, cost, CTR, conversions, and CPA. Supports MANUAL_CPC (requires default_max_cpc_bid_micros), MAXIMIZE_CLICKS, and MAXIMIZE_CONVERSIONS strategies. Budget is in micros (10000000 = $10). Examples: forecast a $50/day campaign with exact-match keywords, or compare BROAD vs EXACT match performance.", "tags": [ "generate-keyword-forecast-metrics" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "The keyword text" }, "match_type": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ], "default": "BROAD", "description": "Keyword match type (default: BROAD)" }, "max_cpc_bid_micros": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-keyword max CPC bid in micros. Overrides the ad-group-level default." } }, "required": [ "text" ], "additionalProperties": false }, "minItems": 1, "maxItems": 200, "description": "Keywords to forecast (1-200). Each has text, optional match_type, optional max_cpc_bid_micros." }, "daily_budget_micros": { "type": "integer", "exclusiveMinimum": 0, "description": "Daily budget in micros (e.g., 10000000 = $10.00)" }, "default_max_cpc_bid_micros": { "type": "integer", "exclusiveMinimum": 0, "description": "Default max CPC bid in micros. Required for MANUAL_CPC strategy. Per-keyword bids override this." }, "bidding_strategy": { "type": "string", "enum": [ "MANUAL_CPC", "MAXIMIZE_CLICKS", "MAXIMIZE_CONVERSIONS" ], "default": "MANUAL_CPC", "description": "Bidding strategy: MANUAL_CPC (default), MAXIMIZE_CLICKS, or MAXIMIZE_CONVERSIONS" }, "max_cpc_bid_ceiling_micros": { "type": "integer", "exclusiveMinimum": 0, "description": "Max CPC bid ceiling for MAXIMIZE_CLICKS strategy (micros). Ignored for other strategies." }, "geo_targets": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2 }, "minItems": 1, "default": [ "US" ], "description": "ISO 3166-1 alpha-2 country codes (e.g., [\"US\", \"GB\"]). Default: [\"US\"]." }, "language": { "type": "string", "minLength": 2, "maxLength": 2, "default": "en", "description": "ISO 639-1 language code (e.g., \"en\", \"es\"). Default: \"en\"." }, "network": { "type": "string", "enum": [ "GOOGLE_SEARCH", "GOOGLE_SEARCH_AND_PARTNERS" ], "default": "GOOGLE_SEARCH", "description": "Ad network: GOOGLE_SEARCH (default) or GOOGLE_SEARCH_AND_PARTNERS" }, "forecast_start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Forecast period start date (YYYY-MM-DD). Defaults to tomorrow." }, "forecast_end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Forecast period end date (YYYY-MM-DD). Defaults to 30 days from start." }, "negative_keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Negative keyword texts to exclude from the forecast" }, "conversion_rate": { "type": "number", "minimum": 0, "maximum": 1, "description": "Expected conversion rate (0-1, e.g., 0.05 for 5%)" }, "currency_code": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 currency code (e.g., \"USD\", \"EUR\"). Defaults to account currency." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "keywords", "daily_budget_micros", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "manual-cpc-forecast": { "summary": "Manual CPC forecast", "value": { "customer_id": "1234567890", "keywords": [ { "text": "running shoes", "match_type": "EXACT" } ], "daily_budget_micros": 10000000, "default_max_cpc_bid_micros": 1500000, "bidding_strategy": "MANUAL_CPC", "reason": "Budget planning for new campaign" } }, "maximize-clicks": { "summary": "Maximize clicks", "value": { "customer_id": "1234567890", "keywords": [ { "text": "yoga mat" }, { "text": "yoga accessories" } ], "daily_budget_micros": 5000000, "bidding_strategy": "MAXIMIZE_CLICKS", "reason": "Estimate traffic potential" } }, "with-date-range": { "summary": "With date range", "value": { "customer_id": "1234567890", "keywords": [ { "text": "winter coats", "match_type": "BROAD" } ], "daily_budget_micros": 20000000, "default_max_cpc_bid_micros": 2000000, "forecast_start_date": "2025-11-01", "forecast_end_date": "2025-12-31", "reason": "Holiday season forecast" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_generate_ad_group_themes": { "post": { "operationId": "google_ads_generate_ad_group_themes", "summary": "Generate Google Ads Ad Group Themes", "description": "Suggest which ad group each keyword belongs to. Takes a list of keywords and existing ad group resource names, returns keyword-to-ad-group assignment suggestions with recommended match types. Also identifies unusable ad groups. Example: organize [\"running shoes\", \"trail shoes\", \"yoga mat\", \"yoga block\"] across your existing ad groups.", "tags": [ "generate-ad-group-themes" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "keywords": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 2000, "description": "Keywords to find ad group assignments for (1-2000 keywords)" }, "ad_groups": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Ad group resource names (e.g., \"customers/1234567890/adGroups/111222333\") to consider as placement targets" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "keywords", "ad_groups", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "assign-keywords-to-ad-groups": { "summary": "Assign keywords to ad groups", "value": { "customer_id": "1234567890", "keywords": [ "running shoes", "trail shoes", "yoga mat", "yoga block" ], "ad_groups": [ "customers/1234567890/adGroups/111", "customers/1234567890/adGroups/222" ], "reason": "Organize keywords into ad groups" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_keyword_performance": { "post": { "operationId": "google_ads_get_keyword_performance", "summary": "Get Google Ads Keyword Performance", "description": "Get keyword-level performance metrics including quality score, match type, status, and search impression share. Supports segments parameter (e.g., ad_network_type) for channel-level breakdown — use to compare Search vs Search Partners per keyword. Includes a parallel conversion breakdown by ad group. Always fetches fresh data.", "tags": [ "keyword-performance" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "keyword_match_type": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ], "description": "Filter by match type: EXACT, PHRASE, BROAD" }, "status": { "type": "array", "items": { "type": "string", "enum": [ "ENABLED", "PAUSED", "REMOVED" ] }, "description": "Filter by keyword status: ENABLED, PAUSED, REMOVED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Maximum number of rows to return (1-1000, default 100)" }, "order_by": { "type": "string", "enum": [ "impressions", "clicks", "cost", "conversions", "ctr" ], "description": "Sort by metric (descending): impressions, clicks, cost, conversions, ctr" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split keyword metrics by channel (SEARCH vs SEARCH_PARTNERS)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "top-keywords": { "summary": "Top keywords", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Keyword performance review" } }, "exact-match-only": { "summary": "Exact match only", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "keyword_match_type": "EXACT", "reason": "Exact match keyword analysis" } }, "top-converters": { "summary": "Top converters", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "order_by": "conversions", "status": [ "ENABLED" ], "reason": "Find top converting keywords" } }, "by-network-channel": { "summary": "By network channel", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "ad_network_type" ], "reason": "Keyword performance by ad network" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_search_terms_report": { "post": { "operationId": "google_ads_get_search_terms_report", "summary": "Get Google Ads Search Terms Report", "description": "Get actual search queries that triggered ads, with performance metrics and keyword match status. Google may not disclose all terms for privacy. Supports segments parameter (e.g., ad_network_type) for channel-level breakdown — use to compare Search vs Search Partners per search term. Always fetches fresh data. Conversion breakdown (keyed by search term) and landing page lookups are opt-in to control response size. Passing conversion_action_name in segments auto-enables conversion breakdown. For Performance Max campaigns, set pmax_search_categories=true to get search category insights (grouped themes) instead of individual search terms.", "tags": [ "search-terms-report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "search_term_status": { "type": "array", "items": { "type": "string", "enum": [ "ADDED", "EXCLUDED", "ADDED_EXCLUDED", "NONE" ] }, "description": "Filter by search term status: ADDED, EXCLUDED, ADDED_EXCLUDED, NONE" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Maximum number of rows to return (1-1000, default 100)" }, "order_by": { "type": "string", "enum": [ "impressions", "clicks", "cost", "conversions", "ctr" ], "description": "Sort by metric (descending): impressions, clicks, cost, conversions, ctr" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\"." }, "include_conversion_breakdown": { "type": "boolean", "default": false, "description": "When true, runs a parallel query to include conversion breakdown by search term and conversion action (keyed by search term text). Adds significant response size — omit when response size is a concern. Default: false." }, "include_landing_pages": { "type": "boolean", "default": false, "description": "When true, runs a parallel query against ad_group_ad to fetch final_urls for each ad group in the results. Returns landing_pages_by_ad_group map keyed by ad_group_id. Default: false." }, "pmax_search_categories": { "type": "boolean", "default": false, "description": "When true, queries campaign_search_term_insight for PMax search category data (grouped themes, not individual queries). ad_group_id and search_term_status are ignored in this mode. Default: false." }, "segments": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "Segments to break down by (e.g., ad_network_type, device). Use ad_network_type to split search term metrics by channel (SEARCH vs SEARCH_PARTNERS). If conversion_action or conversion_action_name is included, it is automatically stripped from the main query and a parallel conversion breakdown query runs instead. Ignored when pmax_search_categories is true." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "top-search-terms": { "summary": "Top search terms", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "reason": "Search term analysis" } }, "new-terms-only": { "summary": "New terms only", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "search_term_status": [ "NONE" ], "order_by": "conversions", "reason": "Find new converting search terms" } }, "with-landing-pages": { "summary": "With landing pages", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "include_landing_pages": true, "reason": "Find which landing pages top search terms go to" } }, "pmax-search-categories": { "summary": "PMax search categories", "value": { "customer_id": "1234567890", "campaign_id": "5555555555", "date_preset": "LAST_30_DAYS", "pmax_search_categories": true, "reason": "PMax search category analysis" } }, "by-network-channel": { "summary": "By network channel", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "ad_network_type" ], "reason": "Search terms by ad network" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_landing_page_report": { "post": { "operationId": "google_ads_get_landing_page_report", "summary": "Get Landing Page Performance Report", "description": "Landing page performance report from the landing_page_view resource. Preferred tool for all landing page analysis — do not use google_ads_get_insights or google_ads_list_ads for landing page data. Returns clicks, impressions, cost, conversions, speed_score, and mobile_friendly_clicks_percentage grouped by landing page URL, with per-conversion-action breakdowns included automatically. Use url_contains to filter by URL pattern. Note: Performance Max campaigns do not appear in landing_page_view data.", "tags": [ "landing-page-report" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1, "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "minLength": 1, "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "segments": { "type": "array", "items": { "type": "string", "enum": [ "date", "device", "ad_network_type" ] }, "description": "Additional segments: date, device, ad_network_type. Conversion breakdowns are always included automatically via a separate query." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "minLength": 1, "description": "Filter to a specific ad group ID" }, "url_contains": { "type": "string", "description": "Filter landing pages where URL contains this string (case-sensitive)" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "Maximum number of landing pages to return (default: 100, max: 1000)" }, "order_by": { "type": "string", "enum": [ "impressions", "clicks", "cost", "conversions", "ctr" ], "default": "clicks", "description": "Sort results by this metric (default: clicks, descending)" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (all_conversions, all_conversions_value) segmented by conversion_action_name." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "top-landing-pages-by-clicks": { "summary": "Top landing pages by clicks", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "reason": "Landing page analysis" } }, "daily-landing-page-trend": { "summary": "Daily landing page trend", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "segments": [ "date" ], "reason": "Daily landing page trend" } }, "landing-pages-for-a-campaign": { "summary": "Landing pages for a campaign", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "campaign_id": "9876543210", "reason": "Campaign landing page review" } }, "filter-by-url-pattern": { "summary": "Filter by URL pattern", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "url_contains": "/products/", "reason": "Product page performance" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_negative_keyword_lists": { "post": { "operationId": "google_ads_list_negative_keyword_lists", "summary": "List Google Ads Negative Keyword Lists", "description": "List shared negative keyword lists at the account level. Optionally includes the keywords within each list and which campaigns each list is attached to. Use for auditing shared exclusion lists and finding coverage gaps.", "tags": [ "negative-keyword-lists" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "list_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific shared set ID to see its keywords and campaign associations" }, "include_keywords": { "type": "boolean", "default": false, "description": "Include the keywords in each list. Defaults to false for overview." }, "include_campaign_associations": { "type": "boolean", "default": false, "description": "Include which campaigns each list is attached to. Defaults to false." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of lists per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "all-lists": { "summary": "All lists", "value": { "customer_id": "1234567890", "reason": "Audit shared negative keyword lists" } }, "with-keywords": { "summary": "With keywords", "value": { "customer_id": "1234567890", "include_keywords": true, "reason": "View all negative keyword list contents" } }, "single-list-detail": { "summary": "Single list detail", "value": { "customer_id": "1234567890", "list_id": "5555555555", "include_keywords": true, "include_campaign_associations": true, "reason": "Full audit of a specific list" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_list_negative_keywords": { "post": { "operationId": "google_ads_list_negative_keywords", "summary": "List Google Ads Negative Keywords", "description": "List negative keywords at the campaign and/or ad-group level. Supports filtering by campaign, ad group, match type, and level. Always fetches fresh data. Use this during search term audits to cross-check recommended negatives against existing ones.", "tags": [ "negative-keywords" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "pattern": "^[\\d-]+$", "description": "MCC (Manager) Customer ID; required for managed accounts" }, "campaign_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "pattern": "^\\d+$", "description": "Filter to a specific ad group ID" }, "level": { "type": "string", "enum": [ "CAMPAIGN", "AD_GROUP", "ALL" ], "default": "ALL", "description": "Which level of negative keywords to return. Defaults to ALL." }, "match_type": { "type": "array", "items": { "type": "string", "enum": [ "EXACT", "PHRASE", "BROAD" ] }, "description": "Filter by match type: EXACT, PHRASE, BROAD" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of negative keywords per page (default: 20, max: 100)" }, "cursor": { "type": "string", "minLength": 1, "description": "Pagination cursor from previous response" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "all-negatives": { "summary": "All negatives", "value": { "customer_id": "1234567890", "reason": "Audit negative keywords" } }, "campaign-level": { "summary": "Campaign level", "value": { "customer_id": "1234567890", "campaign_id": "5555555555", "level": "CAMPAIGN", "reason": "Cross-check campaign negatives during search term audit" } }, "filter-by-match-type": { "summary": "Filter by match type", "value": { "customer_id": "1234567890", "match_type": [ "BROAD" ], "reason": "Find broad match negatives that may be too aggressive" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_performance_report": { "post": { "operationId": "google_ads_get_performance_report", "summary": "Get Google Ads Performance Report", "description": "Comprehensive performance report with funnel metrics and per-conversion-action breakdowns. Supports segments for device breakdown (DESKTOP, MOBILE, TABLET), daily trends, and network type analysis. Preferred over google_ads_get_insights for standard analysis. Runs parallel queries for top-level funnel and conversion action breakdown. Search impression share is included at CAMPAIGN and AD_GROUP levels (budget-lost variants campaign-level only). Use google_ads_get_insights for custom metric selection. For geographic data, use google_ads_get_geo_performance instead.", "tags": [ "reporting" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "minLength": 1, "description": "The Google Ads Customer ID (10 digits, with or without dashes)" }, "login_customer_id": { "type": "string", "minLength": 1, "description": "MCC (Manager) Customer ID; required for managed accounts" }, "date_preset": { "type": "string", "enum": [ "TODAY", "YESTERDAY", "LAST_7_DAYS", "LAST_30_DAYS", "THIS_MONTH", "LAST_MONTH" ], "description": "Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH" }, "date_range": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Start date (YYYY-MM-DD)" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "End date (YYYY-MM-DD)" } }, "required": [ "start_date", "end_date" ], "additionalProperties": false, "description": "Custom date range {start_date, end_date} in YYYY-MM-DD" }, "level": { "type": "string", "enum": [ "ACCOUNT", "CAMPAIGN", "AD_GROUP", "AD" ], "default": "CAMPAIGN", "description": "Report level (default: CAMPAIGN): ACCOUNT, CAMPAIGN, AD_GROUP, AD" }, "segments": { "type": "array", "items": { "type": "string", "enum": [ "date", "device", "ad_network_type" ] }, "description": "Additional segments for the main metrics: date, device, ad_network_type. Conversion action breakdowns are always included automatically via a separate query." }, "campaign_id": { "type": "string", "minLength": 1, "description": "Filter to a specific campaign ID" }, "ad_group_id": { "type": "string", "minLength": 1, "description": "Filter to a specific ad group ID" }, "include_all_conversions": { "type": "boolean", "description": "When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked \"Include in Conversions\" (e.g., view-through, cross-device, store visits)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "customer_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "campaign-overview": { "summary": "Campaign overview", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "reason": "Monthly performance review" } }, "daily-trend": { "summary": "Daily trend", "value": { "customer_id": "1234567890", "date_preset": "LAST_7_DAYS", "segments": [ "date" ], "reason": "Daily performance trend" } }, "account-summary": { "summary": "Account summary", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "level": "ACCOUNT", "reason": "Account-level overview" } }, "device-breakdown": { "summary": "Device breakdown", "value": { "customer_id": "1234567890", "date_preset": "LAST_30_DAYS", "segments": [ "device" ], "reason": "Device analysis" } } } } } }, "responses": { "200": { "description": "JSON report data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_ping": { "post": { "operationId": "google_ads_ping", "summary": "Ping Google Ads MCP Server", "description": "Health check for the Google Ads MCP server.", "tags": [ "auth" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 100, "description": "Optional message to echo back" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "health-check": { "summary": "Health check", "value": { "reason": "Verify server is running" } }, "with-message": { "summary": "With message", "value": { "message": "hello", "reason": "Test connectivity" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_store_preference": { "post": { "operationId": "google_ads_store_preference", "summary": "Store Google Ads Preference", "description": "Store a persistent preference for a Google Ads entity. Use when you infer a recurring preference about analysis, reporting, or management. Updates existing keys.", "tags": [ "preferences" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set (Meta ad sets / Google ad groups), or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID (e.g. act_123456, 23842453456789)" }, "key": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Preference key (e.g. preferred_conversion_metric, budget_alert_threshold)" }, "value": { "description": "Preference value — string, number, boolean, or JSON object" }, "source": { "type": "string", "enum": [ "agent", "user", "system" ], "default": "agent", "description": "Who set this preference: agent (default), user, or system" }, "note": { "type": "string", "maxLength": 500, "description": "Optional context about why this preference was set" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "key", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "set-metric": { "summary": "Set metric", "value": { "entity_type": "ad_account", "entity_id": "1234567890", "key": "preferred_conversion_metric", "value": "conversions", "reason": "User wants conversions as default metric" } }, "set-threshold": { "summary": "Set threshold", "value": { "entity_type": "campaign", "entity_id": "456", "key": "budget_alert_threshold", "value": 0.8, "reason": "Alert at 80% budget" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_get_preferences": { "post": { "operationId": "google_ads_get_preferences", "summary": "Get Google Ads Preferences", "description": "Get all stored preferences for a Google Ads entity. Preferences are also automatically attached to entity-listing tool responses as _stored_preferences, so you often don't need to call this explicitly.", "tags": [ "preferences" ], "x-mcp-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set, or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "get-prefs": { "summary": "Get prefs", "value": { "entity_type": "ad_account", "entity_id": "1234567890", "reason": "Check stored preferences" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } }, "/tools/google_ads_delete_preference": { "post": { "operationId": "google_ads_delete_preference", "summary": "Delete Google Ads Preference", "description": "Delete a stored preference for a Google Ads entity by key. No-op if the preference doesn't exist.", "tags": [ "preferences" ], "x-mcp-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": false }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entity_type": { "type": "string", "enum": [ "ad_account", "campaign", "ad_set", "ad" ], "description": "Type of ad entity: ad_account, campaign, ad_set, or ad" }, "entity_id": { "type": "string", "minLength": 1, "description": "The platform entity ID" }, "key": { "type": "string", "minLength": 1, "description": "The preference key to delete" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this tool call is needed" } }, "required": [ "entity_type", "entity_id", "key", "reason" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" }, "examples": { "delete-pref": { "summary": "Delete pref", "value": { "entity_type": "campaign", "entity_id": "456", "key": "budget_alert_threshold", "reason": "User no longer wants budget alerts" } } } } } }, "responses": { "200": { "description": "Markdown-formatted result with structured content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolResult" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpError" } } } }, "404": { "description": "Tool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } }, "422": { "description": "Invalid parameters — request body failed schema validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Supabase JWT or hpk_live_... API key" } }, "schemas": { "McpToolResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "text", "resource_link" ] }, "text": { "type": "string" } } } }, "structuredContent": { "type": "object", "additionalProperties": true }, "isError": { "type": "boolean" } } }, "McpError": { "type": "object", "properties": { "isError": { "type": "boolean", "const": true }, "content": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string" } } } } } }, "RestError": { "type": "object", "description": "Error response from REST tool endpoints (mapped from JSON-RPC error codes)", "properties": { "error": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "integer", "description": "JSON-RPC error code" }, "data": { "description": "Additional error context" } }, "required": [ "error", "code" ] }, "ToolList": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true } } } } } } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "discovery", "description": "Tool discovery and introspection" }, { "name": "account-summary", "description": "Account-summary tools" }, { "name": "accounts", "description": "Accounts tools" }, { "name": "activities", "description": "Activities tools" }, { "name": "ad-groups", "description": "Ad-groups tools" }, { "name": "ads", "description": "Ads tools" }, { "name": "audiences", "description": "Audiences tools" }, { "name": "auth", "description": "Auth tools" }, { "name": "auto-applied-recommendations", "description": "Auto-applied-recommendations tools" }, { "name": "campaigns", "description": "Campaigns tools" }, { "name": "chart", "description": "Chart tools" }, { "name": "conversion-actions", "description": "Conversion-actions tools" }, { "name": "feedback", "description": "Feedback tools" }, { "name": "generate-ad-group-themes", "description": "Generate-ad-group-themes tools" }, { "name": "generate-keyword-forecast-metrics", "description": "Generate-keyword-forecast-metrics tools" }, { "name": "generate-keyword-ideas", "description": "Generate-keyword-ideas tools" }, { "name": "geo-performance", "description": "Geo-performance tools" }, { "name": "insights", "description": "Insights tools" }, { "name": "keyword-historical-metrics", "description": "Keyword-historical-metrics tools" }, { "name": "keyword-performance", "description": "Keyword-performance tools" }, { "name": "landing-page-report", "description": "Landing-page-report tools" }, { "name": "mcc-child-accounts", "description": "Mcc-child-accounts tools" }, { "name": "negative-keyword-lists", "description": "Negative-keyword-lists tools" }, { "name": "negative-keywords", "description": "Negative-keywords tools" }, { "name": "preferences", "description": "Preferences tools" }, { "name": "reporting", "description": "Reporting tools" }, { "name": "search-terms-report", "description": "Search-terms-report tools" } ] }