Product Metrics MCP server reference
How the MCP server handles workspaces and properties, what each kind of tool does, the scopes on the consent page, how sign-in works and the hourly limits.
The server has two kinds of tools. Analysis tools read your Google Ads account, your store and your products. API tools (search and execute) run Product Metrics setup through the public API. Every argument, default and limit is in MCP tools.
How workspaces and properties work
A workspace (company) is your business or an agency’s client. A property is one store with its Google Ads account inside a workspace. One connection covers every property you can open. See Workspaces and properties.
-
Analysis tools work on one property. The assistant calls
list_properties, then passes the store’spropertyIdasproperty_idto every other tool. With one property, it uses that one without asking. With several, it asks which store you mean or answers per store. -
API tools work on your whole account.
searchandexecuterun without a property: the operations takecompanyIdandpropertyIdin their paths, so the assistant can set up a new workspace before any property exists. -
Pin one property for a script or agent that should only see one store:
https://www.productmetrics.io/mcp?selectedAccountPropertyId=<propertyId>The analysis tools then take no
property_id. Get thepropertyIdfromlist_properties. The API tools ignore the pin.
Tools at a glance
| Tool | Use it for | Inputs | Result |
|---|---|---|---|
list_properties | The stores you can open | name_contains | Properties with company, Google Ads customer id and currency |
get_store_overview | How the store is doing next to the ads | date_range, compare, breakdown, top_products | Sessions, revenue, conversion rate, shop orders, new and returning customers, profit |
explain_google_ads_change | Why a Google Ads metric moved | metric, date_range, change_date, campaign_ids, campaign_types, campaign_name_contains | The change day, the funnel split, what carries it, account changes before it, store revenue next to it |
get_google_ads_report | Performance by campaign, product, device and more | level, date_range, compare, breakdown, filters, sort_by, limit | Rows with clicks, cost, conversions, value and ROAS |
get_poas_report | Profit on ad spend | level, date_range, compare, campaign_ids, item_ids, only_unprofitable, sort_by | Cost, conversion value, ROAS, gross profit, POAS and profit after ads, with stock and decision per product |
get_google_ads_changes | The account’s change history | date_range, campaign_ids, campaign_name_contains, limit | Who changed what and when, with values before and after (last 30 days) |
get_product_targeting | Listing groups per campaign | campaign_ids, campaign_name_contains, include_paused | Which products each campaign targets |
compare_product_segments | Segments against the campaign setup | date_range, campaign_ids, campaign_types, compare_with | Spend, value and ROAS per segment and per value of the other labels, per campaign |
run_google_ads_query | A custom GAQL query | query (required), max_rows | The query rows |
list_products_to_investigate | Products with a signal worth acting on | signal_kinds, action, sort, segment, category, limit, cursor | Products ranked by money at stake, with their decision and strongest signal |
search_products | Find a product by name or id | query (required), limit | Matching products with their item_id |
get_product_context | Everything about a few products | item_ids (required), detail | The five layers, the decision, signals and suggested labels, with contextVersion |
summarize_groups | Totals per segment or category | by (required), limit | Products, spend, conversion value, ROAS and decision mix per group |
get_changes | What changed since the last run | group_by, limit | Last week against the week before, top movers, signals that appeared or cleared |
get_insights | Store insight cards | spots, feed_key, limit | The stored cards |
get_highlights | Product Segmentation highlights | None | Revenue, ad spend and ROAS, and the spend going to Drainers |
get_inventory_state | Stock and reorder dates | item_ids, filter, limit, cursor | Units, weeks of cover, stockout and reorder dates |
get_competitor_offers | Competitor prices for one product | item_id (required), days | Every seller’s latest price and its gap to yours |
get_product_timeseries | One product’s history | item_id (required), measures, days, grain, format | A daily or weekly series |
get_group_timeseries | A group’s history | item_ids, top_by, segment, category, measures, days, grain | A daily or weekly series |
get_segment_history | When a product changed segment | item_id (required), days | Segment changes with dates |
propose_change | File a change for a person to approve | item_id, change, rationale, context_version (all required) | The filed proposal |
list_proposals | Proposals and how metrics moved after them | status, item_id, limit | Proposals with status and outcome |
query_lake | A read-only SQL SELECT over the store’s data | sql (required), max_rows | Rows with the data age per source |
search | Find a public API operation | code (required), truncate | What your code returns from the OpenAPI document |
execute | Call the public API | code (required), truncate | What your code returns from codemode.request calls |
send_product_metrics_feedback | Tell the Product Metrics team what worked or failed | sentiment, message, context, feature, actor | Receipt |
Every analysis tool except list_properties also takes property_id.
Google Ads analysis
These tools read the Google Ads account linked to the property, live. They never change it.
- Start with
explain_google_ads_changefor “why did … drop”. It answers in one call; useget_google_ads_reportonly to drill further. get_poas_reportis the profit view of the same account: cost against the profit from your store’s orders.explain_google_ads_changeandrun_google_ads_querycount towards the lower hourly limit for expensive tools, as doesquery_lake.
"Why did my Google Ads ROAS drop last week?"
→ list_properties, then explain_google_ads_changeProducts and segments
These tools read Product Metrics data: segments, signals, stock and competitor prices.
- Use
list_products_to_investigateorsearch_productsto find products, thenget_product_contextfor the full picture. - Use
summarize_groupsfor totals per segment or category, andget_changesfor what moved since the last run. get_product_timeseries,get_group_timeseriesandget_segment_historyshow history.
"Which Stars are about to run out of stock?"
→ get_inventory_state with filter reorder_due, then get_product_contextProposals
propose_change files a change (a Merchant Center custom label, a priority, or a task) for a person to approve in Priorities. Nothing is written to Merchant Center until a person approves it. list_proposals shows earlier proposals and, once measured, how the numbers moved in the 28 days after.
API tools: search and execute
search and execute give the assistant the whole public API in two tools (Code Mode). The assistant writes a short JavaScript function; Product Metrics runs it in a sandbox with no network.
searchruns the code against the OpenAPI document, filtered to the operations your connection may call. Nothing is called and nothing changes.executeruns the code withcodemode.request({ method, path, query, body, idempotencyKey, ifMatch, confirm }). Each request runs as the matching CLI command would, with your role.
"Set up Product Metrics for my shop: create the workspace and
connect Google Ads."
→ search, then execute: GET /onboarding, PUT /onboarding/account-type,
POST /onboarding/complete, POST /companies (with an idempotency key),
GET /google-ads/accounts, POST /companies/{companyId}/google-ads/property-connectionsRules the server enforces:
- An operation that deletes data runs only with
confirm: true. The assistant asks you first. - A step only you can take (the Google grant, Shopify approval, checkout) returns a URL. The assistant gives it to you, waits, then reads the status again.
- Secret fields, such as a store setup token, come back hidden. Read them in the Product Metrics app or with the CLI.
- At most 25 requests per
executerun. Results over about 6,000 tokens are cut;truncate: falseallows up to 40,000 characters.
Access control
Product Metrics asks your permission once, on the consent page. It lists the scopes the client asks for; you allow them all or cancel.
| Scope | The consent page shows | What it allows |
|---|---|---|
mcp | Can read: Google Ads, store and product data, to answer questions and suggest improvements you approve | The analysis tools and propose_change |
read | Can read: Google Ads, store and product data, to answer questions | API operations that read (x-scope: read) |
setup | Can change: Google Ads, Merchant Center, store and tracking connections | API operations that connect accounts and stores |
write | Can change: settings, product rules and feeds, and who has access | API operations that change settings, rules, feeds and invite people |
Without setup or write, Can change says “Nothing in your account”.
- Your role applies. The assistant acts as you, with your role in each workspace (
admin,editororviewer). Any member can use the analysis tools; only editors and admins can file proposals. Each API operation names the role it needs. - Your access is checked on every request. If you lose access to a workspace, the assistant loses it at once.
- The analysis tools need Pro on the property and the MCP server turned on for your account. The API tools do not: a new account can set Product Metrics up through them.
- Hourly limits. Up to 5,000 tool calls per person and 20,000 per property each hour; 30 and 120 for the expensive tools. API calls share the API rate limit.
How sign-in works
The server uses OAuth 2.1, so any MCP client that supports it connects with the URL alone.
-
The client calls
https://www.productmetrics.io/mcpand gets401with a pointer to the protected-resource metadata:https://www.productmetrics.io/.well-known/oauth-protected-resource/mcp -
That document names the Product Metrics authorization server (
https://prod-backend.productmetrics.io) and its scopes:mcp,read,setupandwrite. -
The client registers itself (dynamic client registration or a Client ID Metadata Document) and sends you to the Product Metrics consent page with PKCE.
-
You check what the page says the app Can read and Can change, and click Connect with the app’s name (for example Connect Claude). The client swaps the code for a Product Metrics token.
The token works only for the MCP server and the public API: it is not a Product Metrics session and cannot open the app.
- Access tokens last one hour and are renewed automatically.
- 30 days after you connect, the connection ends and you sign in again, however often you use it.
- Two origins.
productmetrics mcp-configprintshttps://prod-backend.productmetrics.io/mcp, the same server on the API’s own origin. Either URL works, and a token from one works on the other.
Disconnect
Remove the connector in your client’s settings. To revoke the app’s tokens on the Product Metrics side as well, ask Product Metrics support: a revoke takes effect within about a minute.