Skip to content
Clients

Product Metrics in Codex

Add the Product Metrics MCP server, skills and productmetrics CLI to the OpenAI Codex CLI, then set up tracking and analyse Google Ads from the terminal.

The OpenAI Codex CLI works with Product Metrics in three ways:

  • MCP server (https://www.productmetrics.io/mcp): reads your stores, products and Google Ads account, and runs setup through the API.
  • Skills: give Codex the exact steps for tasks such as setting up tracking.
  • productmetrics CLI: Codex runs it with JSON output.

You sign in in your browser. There is no API key.

Install

1. Add the MCP server

codex mcp add product-metrics \
  --url https://www.productmetrics.io/mcp

Or add it to ~/.codex/config.toml by hand:

~/.codex/config.toml
[mcp_servers.product-metrics]
url = "https://www.productmetrics.io/mcp"

2. Install the skills

From the project where you run Codex:

npx skills add https://www.productmetrics.io/docs \
  --skill '*' \
  --agent codex \
  -y

This installs set-up-tracking, connect-google-ads, check-tracking, bid-on-profit and analyse-google-ads. Add --global to install them for every project. Needs Node.js 22.20 or later. See Install skills.

3. Install the productmetrics CLI (optional)

Install it from npm (Node.js 22 or later), then check it:

npm install -g @productmetrics/cli
productmetrics --version

To run it once without installing, use npx @productmetrics/cli in place of productmetrics. Codex runs productmetrics like any other command.

Restart Codex after installing.

Authenticate

MCP server. Sign in once from your terminal:

codex mcp login product-metrics

Your browser opens the Product Metrics consent page. Check what Codex Can read and Can change. Signed out, click Continue with Google (it creates an account if you have none) or Sign in under the card: either brings you back to the same page. Then click Connect Codex.

productmetrics CLI. Run this in your own terminal, not through Codex:

# opens the browser and waits up to 5 minutes
productmetrics login
# which API, signed in or not, scopes, expiry
productmetrics status

So that productmetrics never prompts or opens a browser when Codex runs it, set PM_AGENT=1:

echo 'export PM_AGENT=1' >> ~/.zshrc
source ~/.zshrc
echo 'export PM_AGENT=1' >> ~/.bashrc
source ~/.bashrc
[System.Environment]::SetEnvironmentVariable("PM_AGENT", "1", "User")

Restart your terminal after running this.

How it works

  • Analysis tools read live. list_properties picks the store, then tools such as explain_google_ads_change, get_google_ads_report and get_poas_report read your Google Ads account and your store’s margins and stock. They never change Google Ads or your store.
  • Setup runs through Code Mode. search finds an API operation; execute runs code that calls it: setup status, connecting stores and Google Ads, creating conversion actions. Operations that delete something run only after you confirm.
  • Browser steps come back as a link. Google consent, a store install or checkout needs you in a browser. Codex gives you the link, waits, then reads the setup status again. With the CLI, productmetrics exits 4 and puts the URL in next_action.url.
  • Skills load on demand. Codex reads a skill when your request matches its description.
  • The CLI speaks JSON. Codex runs productmetrics help agents first, then passes --json to every command and reads exactly one JSON document from stdout.
  • Secrets stay out of the chat. Fields such as a store setup token never reach the assistant through MCP. productmetrics hides them unless you pass --show-secrets.

Skills and tools

Skills

SkillWhat it does
set-up-trackingServer-side conversion tracking end to end: workspace, store, Google Ads, conversion actions
connect-google-adsConnect a Google Ads account and its Merchant Center, or fix a connection
check-trackingCheck the store, the conversion actions, Enhanced Conversions and the latest purchase
bid-on-profitSet up and check POAS or ROAS bidding in Google Ads and Meta
analyse-google-adsExplain changes, wasted spend and POAS, read-only

MCP tools

ToolDescription
list_propertiesThe stores (properties) you can open; call first
get_store_overviewThe store’s own sales, orders and profit next to the ads
explain_google_ads_changeWhy a Google Ads metric changed, in one call
get_google_ads_reportLive Google Ads performance at any level
get_poas_reportProfit on ad spend per product, campaign or account, with stock
get_google_ads_changesWho changed what in the account, last 30 days
list_products_to_investigateProducts that need attention first
propose_changeFile a proposal that a person approves in Priorities
search / executeThe whole Product Metrics API in Code Mode

All 24 analysis tools and their arguments: MCP tools.

What you can ask

> Where is my Product Metrics setup, and what is the next step?
→ execute (GET /setup/status), or productmetrics setup get-status --json

> Connect my Shopify store to Product Metrics.
→ execute (POST /companies/:companyId/stores), or productmetrics stores connect
  --company-id <company_id> --provider shopify --json
  then gives you the link to approve the install in Shopify Admin

> Create the Product Metrics conversion actions in Google Ads.
→ execute (POST /properties/:propertyId/google-ads/conversion-actions),
  or productmetrics google-ads create-conversion-actions --property-id <property_id>
    --company-id <company_id> --json

> Which products lose money after ads this month?
→ list_properties, then get_poas_report (level: product,
  only_unprofitable: true)

> Did anyone change a budget or target ROAS before last week's drop?
→ list_properties, then get_google_ads_changes, or
  explain_google_ads_change

Configuration

Pin one store

To make the analysis tools read one store without asking, add the property to the URL. search and execute still work on your whole account.

~/.codex/config.toml
[mcp_servers.product-metrics]
url = "https://www.productmetrics.io/mcp?selectedAccountPropertyId=<propertyId>"

Environment variables (productmetrics)

# never prompt, never open a browser, no colours
PM_AGENT=1
# an access token, for CI instead of productmetrics login
PM_TOKEN=...
# another API origin (default https://prod-backend.productmetrics.io)
PM_API_URL=...

The CLI stores its sign-in in ${XDG_CONFIG_HOME:-~/.config}/product-metrics/credentials.json.

Troubleshooting

ProblemFix
Codex says the server needs sign-inRun codex mcp login product-metrics and finish the sign-in in the browser.
“This connection expired or was removed; connect Product Metrics again.”Run codex mcp login product-metrics again. If that fails, remove the server and add it again.
“This connection only has MCP access, so it cannot call the Product Metrics API.”Remove the server, add it again and allow everything the consent page shows.
“The MCP server is not enabled for this account yet.”Ask Product Metrics support to turn it on for your account.
“This property needs a Product Metrics Pro subscription for the MCP server.”Upgrade that store to Pro, or ask about another store.
productmetrics can’t reach the API from CodexCodex’s sandbox may block network access for commands. Allow it for this session, or run productmetrics outside the sandbox.
productmetrics exits 3Not signed in or missing a scope. Run productmetrics login in your own terminal; the hint names the scopes.
productmetrics exits 4A person must finish a step in a browser. Open next_action.url, then ask Codex to check the status again.
Codex doesn’t use a skillRun npx skills list and check it is installed for codex, then restart Codex.

Where next