Which Google services are configured for this server (or for one client), and whether the stored OAuth token works. Call it first when another tool answers not_configured or not_authenticated. Returns one boolean per service, the token storage (os-keyring or file), "token": "ok" or the error, and the package version.

Run a Google Analytics 4 report (Data API runReport): traffic, conversions or revenue split by any dimensions over a date range. Returns the top rows ({"rows": [{dimension: value, metric: number}]}), "totals" over every row, "row_count" and "truncated", the unit and definition of each metric under "metrics", the currency, and a "date_range" resolved to calendar dates in the property's timezone with "data_complete". Use ga4_realtime for the last 30 minutes.

Compare a GA4 period with an earlier one in ONE call (Data API runReport with two date ranges): this month against last month, the last 7 days against the 7 before, a month against the same month last year. Returns, per row, the current and previous value of each metric with the absolute "change" and "change_pct" (percent; None when the previous value is 0), "totals" over every row, the unit and definition of each metric under "metrics", the currency, both "date_range"s resolved to calendar dates in the property's timezone with "data_complete", and "biggest_moves": the 5 rows whose first metric changed the most in absolute terms. A key present in one range only shows the other as 0 and a "present_in" list. Use ga4_report for a single range.

Which GA4 events are marked as key events (conversions), and do they inflate conversions: more key events than sessions, page_view or other engagement events marked as key, contact clicks (phone, e-mail, WhatsApp) marked as key. Two Data API runReport calls: events with eventCount and keyEvents, then the property totals of sessions, keyEvents and ecommercePurchases. Returns "key_events" (event_name, event_count, key_events, share_pct, flags), "totals", "key_events_per_session", "findings" ({code, severity, event_name, detail}), the unit and definition of each metric under "metrics" and a "date_range" with "data_complete". Heuristics: check in GA4 Admin > Events > Key events before changing anything. Run it first on a new property, before reading any conversion rate or ROAS.

GA4 realtime report for the last 30 minutes. Useful to check a tracking change, for example that one page view is counted once and not twice. Returns {"rows": [...], "row_count": n, "totals": {...}, "metrics": {...}}.

GA4 accounts and properties the authorized Google account can read (Admin API accountSummaries), so the assistant can find a property id itself and pass it as property_id to ga4_report or ga4_realtime. Returns {"properties": [{property_id, property_name, property_type, account_id, account_name, configured}], "configured_property_id"}. Needs the Google Analytics Admin API enabled; no extra OAuth scope. With a client registry each property also says whether it belongs to the client ("owned"): only those can be queried.

Google Search Console search performance for the configured property: clicks, impressions, CTR and average position, split by query, page, country, device or date. Returns the top rows, "totals" for the whole period (same filter, no split), "truncated", the unit and definition of each metric under "metrics", and a "date_range" in Pacific Time (Search Console's timezone) with "data_complete".

Search Console week-over-week moves: the queries (or pages) that lost and gained the most clicks, last N days against the N days before, with clicks, impressions, CTR and position for both periods, plus totals and both date ranges. A key absent from one period counts as a full loss or a full gain. Read only.

Search Console opportunities: the queries (or pages) ranking between min_position and max_position with at least min_impressions ("striking_distance"), and the ones with impressions but zero clicks ("no_clicks"), each sorted by impressions. One request over the last N days ending 2 days ago. Read only.

Google index status of one URL (URL Inspection API): verdict, coverage state, user and Google-selected canonical, robots.txt state, page fetch state and last crawl time. Quota: 2,000 inspections per day.

Sitemaps declared in Search Console, with last submission, last download, errors and warnings.

Merchant Center data sources (feeds): labels, countries, languages, fetch URLs.

Merchant Center products with their item-level issues (disapprovals, demotions, warnings) per destination, with the attribute to fix. Scans every page of products up to max_pages. Returns {"products": [{offer_id, feed_label, title, link, issues: [{code, severity, description, attribute, destination}]}], "scanned": n, "truncated": bool}.

Run a Merchant Center report (Merchant API reports:search) with an MCQL query, for example product status or free-listing performance. Returns Google's raw result rows.

Tags (type, paused, firing triggers, parameters), triggers and variables of the configured Google Tag Manager container's default workspace, plus the id of the live published version. Built-in trigger ids are translated, e.g. All Pages. Useful to spot a tag configured twice.

Latest Indexing API notifications (URL_UPDATED / URL_DELETED) Google holds for a URL. Read only: nothing is submitted. Most URLs were never notified, which is reported as such.

Lighthouse performance and SEO scores (0 to 100) plus LCP, CLS and TBT for a URL, and the Chrome UX Report field category when Google has real-user data. Set PAGESPEED_API_KEY to avoid the shared anonymous quota.

Google Ads customer accounts the Google Ads token can read directly (customers:listAccessibleCustomers), with the configured customer (GADS_CUSTOMER_ID, or the client's) and login customer (manager account), to pick a customer_id for gads_performance or gads_query. Returns {"customers": [{"id"}], "configured_customer_id", "login_customer_id", "cached"} (cached: true when the list comes from the 5-minute discovery cache). With a client registry only the client's own customers are listed ("hidden_customers" counts the others).

Google Ads performance by account, campaign or ad group over a date range: spend, impressions, clicks, conversions, conversion value, CTR, CPC, CPA and ROAS, optionally split by date, device or network. Built from fixed aggregated GAQL templates (searchStream), highest spend first. Returns "rows", "totals" (ROAS = sum of values / sum of spends) with "totals_complete". start_date and end_date are required (empty -> invalid_dates), the "currency" (looked up when no row), a "date_range" in the account timezone with "data_complete", the unit and definition of each metric, and the "attribution" used.

Run a free read-only Google Ads Query Language (GAQL) SELECT on one customer (searchStream), for fields the fixed gads_performance templates do not cover. Refused without any network call unless it is a single SELECT with no ';' and no '--' or '/' (refused even inside a string literal). The read is bounded: without LIMIT, LIMIT 10001 is added (before PARAMETERS); a larger LIMIT is lowered to 10001; the answer is capped at 20 MB. One SELECT and one FROM only, no JOIN, no backslash, ASCII only outside string literals. FROM and every dotted name prefix in SELECT, WHERE and ORDER BY (besides metrics and segments) must be a reporting resource: customer, campaign, campaign_budget, ad_group, ad_group_ad, ad_group_criterion, keyword_view, shopping_performance_view, product_group_view, asset_group, asset_group_listing_group_filter, asset_group_asset, asset, ad_group_ad_asset_view, campaign_criterion, geographic_view, gender_view, age_range_view, landing_page_view, expanded_landing_page_view, display_keyword_view, topic_view, bidding_strategy, conversion_action, location_view, distance_view, with customer. limited to id, descriptive_name, currency_code, time_zone, status, manager, test_account and resource_name; anything else is refused with resource_not_allowed. Names exposing personal data (change_event, click_view, call_view, search term views, leads, user_*, payments_*, billing_*, customer_user_access, invoices, account links, placements...) are refused anywhere in the query with sensitive_resource. Setting GADS_ALLOW_SENSITIVE_QUERIES=1 in the server env lifts both lists (personal data possible). Rows are flattened to GAQL field names (campaign.name, metrics.clicks); micros fields are converted to currency units: micros renamed without the suffix (metrics.cost_micros -> metrics.cost), metrics.average_cpc, average_cpm, average_cost and cost_per kept under their name.

Google Ads conversion actions of one customer and the settings that decide what metrics.conversions counts: name, status, type, category, origin, primary_for_goal, include_in_conversions_metric, counting type (one or every conversion per click), attribution model, click-through and view-through lookback windows (days) and default value / currency. Fixed GAQL template on conversion_action (searchStream), sorted by name; REMOVED actions are left out unless include_removed. Use it to explain why conversions differ from another platform.

List the Meta ad accounts the access token can read (id act_..., name, status, currency, timezone).

Use it to find the account id for META_AD_ACCOUNT_ID or for the account_id argument of meta_insights. With a client registry only the client's own accounts are listed (not_owned_hidden counts the others).

Meta Ads performance (spend, impressions, clicks, reach, purchases, purchase value, ROAS) by level.

ctr is recomputed as a ratio 0..1, ROAS = purchase value / spend (totals: sum of values / sum of spends), Meta's own purchase_roas is kept raw in meta_reported_roas. Currency is the ad account's, never converted.

List the campaigns of a Meta ad account: id, name, status, effective_status, objective, daily and lifetime budget (minor units and currency units), special_ad_categories, dates. Read-only.

Use the ids with meta_plan_pause / meta_plan_budget_change, or meta_adsets(campaign_id=...).

List the ad sets of a Meta ad account (optionally of one campaign): id, name, campaign_id, status, effective_status, daily and lifetime budget (minor units and currency units), optimization goal, billing event, bid strategy, dates. Read-only.

List the ads of a Meta ad account (optionally of one ad set or campaign): id, name, campaign_id, adset_id, status, effective_status, creative_id, dates. Read-only.

OpenAI Ads (ChatGPT ads) ad account of the client's key (GET /v1/ad_account): only id, name, status, currency_code (the account currency), timezone when present; every other key is dropped and listed in raw_fields_dropped. Use it as a connection test before openai_ads_insights. Cached 300 s ("cached": true). With a registry, refused (account_mismatch) when the key answers for another account than the client's.

OpenAI Ads (ChatGPT ads) performance over a date range: impressions, clicks, spend, ctr, conversions and attributed sales for the ad account or one campaign, ad group or ad. Returns "rows" as reported (flat keys such as campaign_id; null kept, null_means "non calculable"), recomputed "totals" (roas = sum of sales / sum of spend), "currency" (from order_created_attributed_sales_currency, else None), "date_range" in the timezone returned by the API, "next_after" while has_more (reads up to max_rows rows over at most 5 pages), units (spend in major currency units, ctr ratio) and "attribution". No automatic retry.

OpenAI Ads (ChatGPT ads) conversion insights (POST /v1/conversions/insights, a read query): goal conversions (click-through and view-through) and attributed order value per campaign, ad group or ad (entity_ids), or for the whole account (group_by_entity false), over whole days in the account timezone. Returns "rows" (null kept), recomputed "totals", "currency" (account_currency), "attribution" and "date_range". No pagination: more than 2000 rows answers too_many_rows (fewer entities, shorter period or fewer event_names). Warning: attributed event details may contain order or user identifiers; only documented aggregate fields are kept.

List the OpenAI Ads (ChatGPT ads) campaigns of the client's ad account (GET /v1/campaigns): id, name, status (active, paused, archived), bidding_type, budget (daily_spend_limit_micros or lifetime_spend_limit_micros, micros of the account currency), start_time / end_time (unix seconds), mode, created_at / updated_at. Use the ids with openai_ads_ad_groups, openai_ads_insights or openai_ads_plan_pause. Reads up to limit rows (next_after while has_more). Names are third-party text.

List the ad groups of one OpenAI Ads (ChatGPT ads) campaign (GET /v1/ad_groups?campaign_id=...): id, name, status, bidding_config (billing_event_type, max_bid_micros in micros of the account currency), created_at / updated_at. Reads up to limit rows (next_after while has_more). Names are third-party text.

List the ads of one OpenAI Ads (ChatGPT ads) ad group (GET /v1/ads?ad_group_id=...): id, name, status, review_status (in_review, rejected, approved), creative (type, title, body, price, target_url, file_id), created_at / updated_at. Reads up to limit rows (next_after while has_more). Names and creative texts are third-party text.

Google Ads, Meta and OpenAI Ads totals side by side for one period: spend, impressions, clicks, conversions and conversion value as reported by each platform, the platform's own ROAS, currency, attribution windows and date range. A platform not configured or failing gets its own block without blocking the others (partial). combined adds spends only when every currency is the same (else null with combined_reason; a platform without activity adds zeros and needs no currency) and computes ROAS as total value / total spend. Conversions overlap between platforms: their sum is not deduplicated (warning). Multi-client: one client only (client_id), and only the platforms that client has; never two clients mixed.

Custom dimensions and custom metrics of a GA4 property (parameter name, display name, scope, unit) and how many slots each scope uses against the standard quotas (50 event, 25 user, 10 item dimensions; 50 metrics). Read only.

Key events (formerly conversions) of a GA4 property: event name, counting method, default value, whether it is custom and deletable. Read only.

PLAN (nothing is written): mark an event as a key event of the client's GA4 property. Returns the plan with a confirmation_token; apply it with google_apply after the user agreed. No automatic rollback (deleting a key event is not offered in this version: remove it in GA4 Admin > Key events).

PLAN (nothing is written): register a custom dimension on the client's GA4 property. Warning: parameterName and scope are immutable and the slot counts against the quota (50 event / 25 user / 10 item). Apply with google_apply after the user agreed. No automatic rollback (archiving is not offered).

Search Console properties the client's Google token can see: address (sc-domain:example.com or a URL prefix), permission level (siteOwner, siteFullUser, siteRestrictedUser, siteUnverifiedUser), whether it is the client's configured site and whether that level may submit sitemaps. With several clients, sites that are not this client's are masked. Read only.

One page of the client's Merchant Center products (processed view): full product id contentLanguagefeedLabelofferId (the id merchant_plan_product_patch takes), title, link, availability, price, primary data source, number of item issues and status per destination. Pass next_page_token for the next page. Read only.

Account-level issues of the client's Merchant Center account (suspensions, policy, shipping, tax, website claim...): title, severity (CRITICAL, ERROR, SUGGESTION), detail, documentation link and impacted destinations per country, with counts by severity. Read only.

Workspaces of the client's GTM container (id, name, whether it is the Default Workspace, whether this server created it) and, for each one, its pending changes (added / updated / deleted tags, triggers, variables) and merge conflicts. Read only; use a non-default workspace for any change.

One tag of a workspace in full (type, parameters, triggers, paused) with its fingerprint, which gtm_plan_tag_upsert needs to update it. Read only.

One trigger of a workspace in full (type, filters) with its fingerprint (needed to update it). Read only.

One variable of a workspace in full (type, parameters) with its fingerprint (needed to update it). Read only.

Container versions of the client's GTM container, newest first (id, name, number of tags, triggers and variables) and which one is live. Read only: publishing is not offered.

PLAN (nothing is written): create a dedicated workspace in the client's GTM container, where the tag, trigger and variable plans can then work (the Default Workspace is never written). Low risk: a workspace changes nothing live. Apply with google_apply after the user agreed. No automatic rollback.

PLAN (nothing is written): create or update a tag in a non-default workspace of the client's GTM container. An update needs the fingerprint from gtm_get_tag. Nothing goes live: publishing stays in the GTM interface. Custom HTML tags are high risk. Apply with google_apply after the user agreed; an update can be undone with rollback_plan.

PLAN (nothing is written): create or update a trigger in a non-default workspace of the client's GTM container (fingerprint from gtm_get_trigger for an update). Apply with google_apply after the user agreed.

PLAN (nothing is written): create or update a variable in a non-default workspace of the client's GTM container (fingerprint from gtm_get_variable for an update). Custom JavaScript variables are high risk. Apply with google_apply after the user agreed.

Preview step of a GTM plan: compile a workspace into a throw-away preview version and report compiler errors, merge conflicts and what it holds. It changes nothing (no version is created, nothing goes live), so there is nothing to apply. Uses the write token (scope tagmanager.edit.containerversions) and needs writes enabled for the client.

PLAN (nothing is written): submit a sitemap to the client's Search Console property. The sitemap URL must be inside the property (same domain or a subdomain for sc-domain:, same prefix for a URL-prefix property). Low risk. Apply with google_apply after the user agreed. A sitemap that was not listed before can be removed again with rollback_plan (needs write.gsc.allow_delete and a human approval); one that was already listed has no rollback.

PLAN (nothing is written): change some attributes of one product of the client's Merchant Center account, with an explicit update mask (an attribute listed without a value is refused: Google would delete it). Title and description are low risk, link and availability medium, price high and financial (needs a human approval; capped by write.merchant.max_daily_budget_micros, max_increase_pct and cap_currency). Only API data sources. Apply with google_apply after the user agreed; changes show after up to 30 minutes; rollback_plan restores the previous values. Product insert, delete and inventories are deliberately not offered.

Plan pausing Google Ads campaigns, ad groups or ads (status PAUSED, nothing else). Each entity is read first (current status kept for the rollback) and dry-run by Google (validateOnly). Ad ids are "<ad_group_id>~<ad_id>". Returns the plan (diff, risks, confirmation_token, confirm): show it to the user, then gads_apply. A paused entity stops spending; rollback_plan re-enables it only if allow_activate is set.

Plan a new daily amount for one Google Ads campaign budget (amountMicros, in micros of the ACCOUNT currency: 12.50 EUR = 12500000). Give budget_id, or campaign_id to change the budget that campaign uses. The current budget and currency are read first; the policy caps it (max_daily_budget_micros in cap_currency, +20 % per 24 h at most) and a human approval is required before gads_apply (financial). A shared budget changes every campaign using it (shown in the plan).

Plan adding negative keywords (1 to 50 texts given by you, match type EXACT, PHRASE or BROAD) to one campaign (campaign_id) or to one shared negative keyword list (shared_set_id), in one atomic request, dry-run by Google first. Negatives only stop ads from showing (no spend increase). Rollback is manual (remove them in the interface).

Plan creating one Google Ads Search campaign, PAUSED, with its own daily budget (amountMicros in micros of the account currency; not shared), Google Search network only, in one atomic request dry-run by Google. No ad group, keyword nor ad is created; the bidding strategy is fixed (manual CPC, no bid amount, not configurable). It stays PAUSED: activate it in the Google Ads interface once it is complete. Financial: human approval before gads_apply.

PLAN (nothing is written): pause Meta campaigns, ad sets or ads (status PAUSED). Reads each entity (account first, then status), checks the change locally (nothing is sent to Meta), returns the signed plan; apply it with meta_apply after the user agrees. Rollback restores the previous status.

PLAN (nothing is written): change the daily budget of a Meta campaign or ad set. Financial: capped by the client's policy (max daily budget in its currency, +20 % in 24 h) and applied only after a human approval out of band (google-ecommerce-mcp approve). Rollback restores the previous budget.

PLAN (nothing is written): create a Meta campaign, always PAUSED. Dry-run with validate_only; apply with meta_apply; activation stays in Ads Manager. No automatic rollback (archive it in Ads Manager).

PLAN (nothing is written): create a Meta ad set, always PAUSED, in a campaign of the client's account (checked). No bid fields (bid caps are refused by the policy). Dry-run with validate_only; apply with meta_apply. No automatic rollback.

PLAN (nothing is written): create a Meta ad, always PAUSED, from an existing creative, in an ad set of the client's account (both checked). Dry-run with validate_only; apply with meta_apply. No automatic rollback.

PLAN (nothing is written): pause OpenAI Ads (ChatGPT ads) campaigns, ad groups or ads. Reads each entity (archived ones are refused, already paused ones are skipped), checks the client's write policy, runs a LOCAL dry-run (the unit endpoints have no validate_only) and returns the plan with confirmation_token and confirm; apply it with openai_ads_apply after the user agreed. Rollback reactivates what was active (that rollback spends money: allow_activate and a human approval). Note: an OpenAI Ads key cannot be read-only; only this server's policy guards writes.

PLAN (nothing is written): set the daily budget (daily_spend_limit_micros) of one OpenAI Ads campaign. Financial: the client's cap, currency and +20 %/24 h locks apply and the user must approve it out of band (google-ecommerce-mcp approve). Lifetime budgets are refused. LOCAL dry-run only. Apply with openai_ads_apply; rollback restores the previous daily budget. An OpenAI Ads key cannot be read-only.

PLAN (nothing is written): create one OpenAI Ads campaign, always with an explicit status "paused" and an explicit start_time, and a daily budget (no targeting, no bidding, no product feed). Financial: cap and currency locks plus an out-of-band human approval. LOCAL dry-run only. Apply with openai_ads_apply; activate it in the ChatGPT Ads interface once its ad groups and ads are ready. An OpenAI Ads key cannot be read-only.

Meta pixel health: last fire time, availability, automatic matching, and the events received per name over the last days days (PageView, ViewContent, AddToCart, Purchase...), with plain warnings (never fired, silent for more than 24 h, no Purchase event).

Conversions API / pixel dataset quality per web event: event match quality (composite score, match key feedback), event coverage, dedup feedback, data freshness and additional conversions reported (ACR). Read only: nothing is sent to the dataset.

Meta catalog diagnostics: issues by type and severity (MUST_FIX, WARNING), e.g. catalog not connected to the pixel, invalid content ids, missing attributes, image quality, policy violations, with the number of affected items.

Products of the client's Meta catalog (bounded list): product item id, retailer_id, name, price, sale_price, currency, availability, inventory, review status, visibility. Use the product item id with meta_eco_plan_catalog_item_update.

Instagram professional account insights, total over the period: reach, views, accounts engaged, interactions (likes, comments, shares, saves, replies), follows and profile link taps. Deprecated metrics (impressions, plays, video_views) are refused.

Facebook Page insights per day and in total: media views (page_media_view replaces the deprecated impressions), post engagements, follows and unfollows, total actions. 90 days at most per request.

PLAN (writes nothing): update one Meta catalog product item (price, sale price, availability, stock). Reads the item first (complete snapshot, rollback restores it), validates locally, and returns a signed plan with confirmation_token and confirm; apply it with meta_apply after the user agrees (a price change also needs google-ecommerce-mcp approve).

WRITE: apply a signed plan for Google Ads, after the user approved it. Pass plan_id, confirmation_token and confirm exactly as the plan_* tool returned them. Every lock is re-checked; ops run in order and stop at the first error; everything is journaled.

WRITE: apply a signed plan for Meta (ads, pixel, catalog, Instagram, Page), after the user approved it. Pass plan_id, confirmation_token and confirm exactly as the plan_* tool returned them. Every lock is re-checked; ops run in order and stop at the first error; everything is journaled.

WRITE: apply a signed plan for ChatGPT Ads (OpenAI), after the user approved it. Pass plan_id, confirmation_token and confirm exactly as the plan_* tool returned them. Every lock is re-checked; ops run in order and stop at the first error; everything is journaled.

WRITE: apply a signed plan for GA4, Search Console, Merchant, GTM, after the user approved it. Pass plan_id, confirmation_token and confirm exactly as the plan_* tool returned them. Every lock is re-checked; ops run in order and stop at the first error; everything is journaled.

Show a stored write plan (ops, risk, changes, requests masked, status). Never returns its token.

List the newest write plans of a client (id, platform, title, status, expiry).

Read the write journal of a client (plans, apply intents and results, rollbacks), secrets masked.

Build a NEW plan undoing what plan_id applied (nothing is written; apply it like any plan).

Clients this server can work on, from the client registry (clients.json): client_id, label, sandbox and which platforms are configured. Never a secret. Without a registry there is one implicit client, "default", built from the environment variables. Pass client_id to the other tools when several clients are listed.

One client's profile: label, sandbox flag, the account ids of each platform (GA4 property, Search Console site, Merchant account, GTM container, Google Ads customer, Meta ad account...) and its write policy per platform (enabled, allowed accounts, budget caps). Never a secret value.

Health of one client: which services are configured, whether its Google token works and which scopes it holds (like server_status), plus whether each of its secrets is stored ("secrets": {kind: true/false}; the values are never read out).