# Supermetrics MCP Server — Full Reference for LLMs

> Supermetrics MCP Server is a Model Context Protocol (MCP) server that connects AI agents and coding assistants to 170+ marketing, advertising, analytics, e-commerce, CRM, and public data platforms. Query live data from Google Ads, Meta Ads, LinkedIn Ads, Google Analytics 4, TikTok Ads, Shopify, HubSpot, Salesforce, and more.

## Server Details

- MCP endpoint: `POST https://mcp.supermetrics.com/mcp`
- Direct tool invocation: `POST https://mcp.supermetrics.com/mcp/{tool_name}`
- OpenAPI spec: `GET https://mcp.supermetrics.com/openapi.json`
- Protocol: JSON-RPC 2.0 (MCP) or direct HTTP

## Authentication

Bearer tokens in Authorization header:
- **OAuth tokens** (recommended): `Authorization: Bearer otok_*`
  - OAuth authorization: `https://api.supermetrics.com/oauth/authorize`
  - OAuth token: `https://api.supermetrics.com/oauth/token`
  - Supports Dynamic Client Registration (DCR) and Client ID Metadata Document (CIMD)
- **API keys**: `Authorization: Bearer api_*`
  - Create at: https://hub.supermetrics.com/api-key-management

No pre-existing Supermetrics account is needed. A Supermetrics account with a 14-day free trial is created automatically on the first login — no credit card required.

## Compatible AI Clients

Supermetrics MCP works with any MCP-compatible AI client, including:
- Claude (Anthropic): https://claude.ai/directory/cc599e7b-8c59-4e89-9bf0-36d47bb9ec80
- ChatGPT: https://chatgpt.com/g/g-I0MDu3qBq-supermetrics-marketing-analytics
- Google Gemini Enterprise: https://cloud.withgoogle.com/agentfinder/product/e978e9d5-2895-41e7-98a3-67e39af1cc45
- Microsoft Copilot: https://m365.cloud.microsoft/chat/?titleId=P_482b5243-c377-5a5d-d187-63349eb2d106
- Cursor, Windsurf, Cline, GitHub Copilot, n8n, Power Automate, Azure Logic Apps, Power Apps

## Core Workflow

1. `data_source_discovery()` — list all sources with auth status; pick one.
2. `data_source_discovery(ds_id=X)` — get its configuration: `has_account_list`, `has_fields`, `has_report_type_selection`, `is_date_range_required`, `report_types`, `common_settings`, `account_labels`.
3. Follow the config:
   - If `has_account_list` is true → `accounts_discovery(ds_id=X)` for account IDs.
   - If `has_report_type_selection` is true → select report type according to user's needs.
   - If a report type has `is_free_text_account_required` → a free-text identifier is needed (page alias, URL, profile name). Pass as `ds_accounts` (never via `settings`).
   - If `has_fields` is true → `field_discovery(ds_id=X)` for metrics and dimensions.
   - Fill in any required settings values based on the user's request or reasonable defaults.
4. `data_query(ds_id=X, ds_accounts=..., fields=..., settings={...})` — run the query.
5. `get_async_query_results(schedule_id=...)` — poll until results are ready.

## Available Tools

### data_source_discovery
Browse available data sources and their capabilities including supported metrics, dimensions, report types, and configuration requirements.
- No parameters required for full catalog
- Pass `ds_id` to get detailed configuration for a specific source
- Returns auth status, login links, account labels, and common settings

### field_discovery
Explore available fields, metrics, and dimensions for a specific data source.
- Required: `ds_id` (e.g., "FA" for Facebook Ads, "AW" for Google Ads, "GAWA" for GA4)
- Optional: `field_type` ("dimension" or "metric")
- Automatically detects currency and monetary fields
- Returns field IDs, display names, descriptions, and compatibility info

### accounts_discovery
Discover and validate connected accounts for a data source.
- Required: `ds_id`
- Returns account IDs, names, and access status
- Use returned account IDs in `data_query` calls

### data_query
Execute async data queries against the Supermetrics API.
- Required: `ds_id`, `ds_accounts`, `fields`
- Optional: `date_range_type`, `start_date`, `end_date`, `settings` (JSON object with report_type and other settings)
- Returns `schedule_id` for async result retrieval
- Pass `report_type` and all setting values inside the `settings` parameter

### get_async_query_results
Retrieve results of data queries using schedule_id.
- Required: `schedule_id` (from data_query response)
- Poll until status is complete — do not stop on "scheduled", "queued", or "running"

### user_info
Retrieve authenticated user profile, team information, and license details.
- No parameters required
- Returns name, email, team info, license status, expiration dates

### get_today
Get current date information for query parameters.
- Use when constructing custom date ranges
- Helps resolve relative date references ("last month", "past 7 days")

### contact_supermetrics
Send product feedback or create a support ticket or sales enquiry.

### campaign_and_resource_get *(Beta)*
Get campaign details, list campaigns, and explore related resources.
- List campaigns with status filtering and detail levels (full, campaign, ad_group)
- Campaign health checks with performance snapshots
- Keyword research: idea generation and search volume lookups (Google Ads, Microsoft Ads)
- Targeting catalog search and audience reach estimation
- Asset library browsing, audience discovery, optimization recommendations
- Campaign change history and conversion action discovery
- Supported platforms: Google Ads, Meta Ads, Microsoft Ads, TikTok Ads, LinkedIn Ads

### campaign_create *(Beta)*
Create advertising campaigns including ad groups and ads in a single call.
- Full campaign creation with budget, targeting, bidding, and scheduling
- Text ads (RSA), display ads, video ads, carousel ads, lead form ads
- AI image generation from text prompts
- Ad extensions: sitelinks, structured snippets, images
- Campaigns always created as PAUSED for safe review before launch
- Supported platforms: Google Ads, Meta Ads, Microsoft Ads, TikTok Ads, LinkedIn Ads

### campaign_update *(Beta)*
Update existing campaigns — change status, budgets, targeting, ads, and more.
- Partial updates: only specified fields are changed
- Enable, pause, or remove campaigns, ad groups, and ads
- Update budgets, bidding strategies, schedules, targeting, ad extensions
- Add new ad groups and ads to existing campaigns

## Supported Data Sources (170+)

### Advertising Platforms
AdRoll, Adform, Amazon Ads, Amazon DSP, Apple Search Ads, Axon by AppLovin, Basis, Beeswax, Capterra PPC, Criteo, Criteo Retail Media, DoubleVerify, Eskimi, Facebook Ads, Facebook Billing Data, Flashtalking, Google Ads, Google Ads Account Explorer, Google Ads Keyword Planner, Google Campaign Manager 360, Google Display & Video 360, Google Search Ads 360, IQM, Integral Ad Science, Kwai Ads, LINE Ads, Lazada Ads, Liftoff, LinkedIn Ads, LiveIntent, MNTN, Microsoft Advertising (Bing), Moloco DSP, Nexxen DSP, Nielsen Digital Ad Ratings, Outbrain Amplify, Outbrain DSP (Zemanta), Pinterest Ads, Quantcast, Quora Ads, RTB House, Rakuten Advertising, Readpeak, Reddit Ads, Shopee Ads, Snapchat Marketing, Spotify Ads, StackAdapt, Taboola, Teads, The Trade Desk, TikTok Ads, Vibe, Walmart Connect (Display), Walmart Connect (Search), X Ads (Twitter), Xing Ads, Yahoo DSP, Yahoo! Japan Display Ads, Yahoo! Japan Search Ads, Yandex.Direct

### Analytics & SEO
Adobe Analytics, Adobe Analytics 2.0, Ahrefs, Amplitude, Bing Webmaster Tools, Google Analytics 4, Google PageSpeed Insights, Google Search Console, Google Trends, Hotjar, Matomo, Mixpanel, Piano Analytics (AT Internet), Piwik PRO, Plausible, Semrush Analytics, Semrush Projects, Similarweb, Yandex.Metrica

### Social Media
Facebook Insights, Facebook Public Data, Instagram Insights, Instagram Public Data, LinkedIn Company Pages, Pinterest Organic, Pinterest Public Data, Slack, Smarp, Snapchat Marketing, Sprout Social, Threads Insights, TikTok Organic, Vimeo Public Data, X Organic (Twitter), YouTube, YouTube Public Data

### E-Commerce
Adobe Commerce (Magento 2), BigCommerce, Centra, Ecwid, Lazada Commerce, PrestaShop, Prisjakt, Recharge, Shopee Commerce, Shopify, Shopware, Squarespace Commerce, Stripe, TikTok Shop, Wix Commerce, WooCommerce

### CRM & Marketing Automation
ActiveCampaign, Brevo, Campaign Monitor, Close CRM, Eloqua, HubSpot, HubSpot Contacts, HubSpot Marketing Emails, HubSpot Marketing Forms, Klaviyo, MailChimp, Marketo, Odoo CRM, Omnisend, Pipedrive, Salesforce, Zoho CRM

### Affiliate & Partner Marketing
Adtraction, Affluent, Awin, CJ Affiliate, Everflow, Impact, Partnerize, Tradedoubler

### App Analytics & Attribution
Adjust, AppsFlyer, Branch, Google Play Console, Google Play Reviews, Apple Public Data

### Review Platforms
Capterra Reviews, G2 Reviews, Glassdoor Reviews, Google Play Reviews, Indeed Reviews, Tripadvisor Reviews, Yelp Reviews, Yext

### Other Platforms
8x8, Bambuser, CallRail, Celtra, Clockify, Data Blending, Gong, Google Ad Manager, Google AdSense, Google BigQuery, Google Merchant Center, Google My Business, Google Sheets, Google Sheets (Legacy), Harvest, Ignite, Meltwater, Simplesat, Snowflake, Snowflake (Legacy), Sprinklr

### No-Auth Sources (Easy Start)
These fetch publicly available data — no authentication needed:
- Facebook Public Data: page data, follower numbers, posts and engagement for any public Facebook page
- Apple Public Data: app ratings, reviews, top lists by country
- Instagram Public Data, Pinterest Public Data, YouTube Public Data, Vimeo Public Data, X Organic (Twitter)

Great for competitor monitoring and quick demos.

## Common Use Cases

- Pull Google Ads spend, CPC, ROAS, and conversion data for performance analysis
- Compare Meta Ads (Facebook Ads) campaign performance across ad sets
- Build automated marketing dashboards combining multiple data sources
- Analyze LinkedIn Ads lead gen form submissions and cost per lead
- Track TikTok Ads ROAS and audience engagement metrics
- Monitor Shopify revenue, orders, and product performance
- Query HubSpot contact and deal pipeline data
- Audit Google Analytics 4 traffic sources and user behavior
- Research keywords and audiences for new ad campaigns
- Create and manage ad campaigns across platforms from AI chat
- Monitor competitor social media performance using public data sources
- Export marketing data for analysis in Jupyter notebooks or spreadsheets
- Build automated weekly reporting pipelines with n8n or Power Automate

## Important Rules for AI Agents

- Never fabricate data — only present actual values from tool responses.
- Never invent setting keys or field IDs — only use values returned by discovery tools.
- Use field IDs from `field_discovery`, not display names.
- When using `date_range_type='custom'`, call `get_today` first to resolve relative dates.
- After `data_query` returns a `schedule_id`, poll `get_async_query_results` until results arrive — do not stop on "scheduled", "queued", or "running".
- When presenting monetary values, use one currency identifier (symbol or code, not both).

## Links

- Supermetrics Hub: https://hub.supermetrics.com/
- Knowledge base: https://docs.supermetrics.com/
- Data source documentation: https://docs.supermetrics.com/docs/connect
- Pricing: https://supermetrics.com/pricing
- Terms of service: https://supermetrics.com/terms-of-service
- Privacy policy: https://supermetrics.com/privacy-policy