{"title":"Supermetrics MCP Server Documentation","format":"markdown","content":"<img src=\"smlogo.svg\" alt=\"Supermetrics\" width=\"300\"/>\n\n# Supermetrics MCP Server — Connect AI Agents to Marketing Data\n\n## Overview\n\nSupermetrics MCP Server is a Model Context Protocol server that lets AI agents and coding assistants — like Claude, Cursor, or GitHub Copilot — query live marketing data directly from Supermetrics. Connect your AI tools to 170+ platforms including Google Ads, Meta Ads, LinkedIn Ads, Google Analytics, TikTok Ads, Microsoft Ads, Pinterest Ads, Snapchat Ads, HubSpot, Salesforce, Shopify, Amazon Ads and more.\n\nNo pre-existing Supermetrics account is needed. A Supermetrics account with a 14-day free trial is created automatically on the first login.\n\n## Compatible AI Clients\n\nSupermetrics MCP works with any MCP-compatible AI client, including:\n- Claude (Anthropic)\n- Cursor\n- Windsurf\n- Cline\n- GitHub Copilot extensions\n- n8n\n- Microsoft Power Automate\n- Azure Logic Apps\n- Power Apps\n- Any application built on the MCP open standard\n\nYou can connect these tools to our MCP server on your own, or use some of the ready-made connectors we offer:\n- [Claude](https://claude.ai/directory/cc599e7b-8c59-4e89-9bf0-36d47bb9ec80)\n- [ChatGPT](https://chatgpt.com/g/g-I0MDu3qBq-supermetrics-marketing-analytics)\n- [Google Gemini Enterprise](https://cloud.withgoogle.com/agentfinder/product/e978e9d5-2895-41e7-98a3-67e39af1cc45)\n- [Microsoft Copilot](https://m365.cloud.microsoft/chat/?titleId=P_482b5243-c377-5a5d-d187-63349eb2d106)\n\n## Features\n\n### Available Tools\n\n- **Data Source Discovery** (`data_source_discovery`): Browse available data sources and their capabilities\n- **Field Discovery** (`field_discovery`): Explore available fields and metrics for each data source\n- **Account Discovery** (`accounts_discovery`): Manage and validate connected accounts across data sources\n- **Data Query** (`data_query`): Execute data queries with real-time status updates and progress monitoring\n- **Async Query Results** (`get_async_query_results`): Retrieve results of data queries using schedule_id\n- **User Information** (`user_info`): Retrieve authenticated user profile, team information, and license details\n- **Get Today** (`get_today`): Get current date information for query parameters\n- **Contact Supermetrics** (`contact_supermetrics`): Send product feedback or create a support ticket or sales enquiry\n\nTools in beta testing:\n- **Campaign & Resource Get** (`campaign_and_resource_get`) *(Beta)*: Get campaign details, list campaigns, and explore related resources like keywords, audiences, and recommendations\n- **Create Campaign** (`campaign_create`) *(Beta)*: Create ad campaigns across Google, Meta, Microsoft and TikTok\n- **Update Campaign** (`campaign_update`) *(Beta)*: Update existing campaigns — change status, budgets, targeting, ads, and more\n\n## Supported Data Sources\n\nThe Supermetrics MCP server connects to 170+ marketing, advertising, analytics, e-commerce, CRM, and public data platforms. This list is dynamically updated — call `data_source_discovery` or visit [/datasources](/datasources) for the latest.\n\n### Advertising Platforms\nAdRoll, 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\n\n### Analytics & SEO\nAdobe 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\n\n### Social Media\nFacebook 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\n\n### E-Commerce\nAdobe Commerce (Magento 2), BigCommerce, Centra, Ecwid, Lazada Commerce, PrestaShop, Prisjakt, Recharge, Shopee Commerce, Shopify, Shopware, Squarespace Commerce, Stripe, TikTok Shop, Wix Commerce, WooCommerce\n\n### CRM & Marketing Automation\nActiveCampaign, 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\n\n### Affiliate & Partner Marketing\nAdtraction, Affluent, Awin, CJ Affiliate, Everflow, Impact, Partnerize, Tradedoubler\n\n### App Analytics & Attribution\nAdjust, AppsFlyer, Branch, Google Play Console, Google Play Reviews, Apple Public Data\n\n### Review Platforms\nCapterra Reviews, G2 Reviews, Glassdoor Reviews, Google Play Reviews, Indeed Reviews, Tripadvisor Reviews, Yelp Reviews, Yext\n\n### Other Platforms\n8x8, 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\n\n## Use Case Examples\n\n- Ask an AI assistant to pull last month's Google Ads spend and compare it to the previous period\n- Let a coding agent build a live marketing dashboard by querying Meta Ads and Google Analytics simultaneously\n- Automate campaign performance reporting by integrating Supermetrics into your AI workflow\n- Explore available metrics and dimensions across platforms before writing a single line of code\n- Validate account connections and troubleshoot data access issues directly from your AI client\n- Create and manage ad campaigns across Google, Meta, Microsoft, TikTok and LinkedIn from your AI chat\n- Monitor competitor social media performance using public data sources — no authentication needed\n- Build automated weekly reporting pipelines with n8n or Power Automate via MCP\n\n\n## Setup Instructions\n\n### Prerequisites\n\n- MCP-compatible client or development environment\n- Authentication with Supermetrics API key or OAuth\n- Supermetrics subscription — a 14-day free trial is created automatically on your first login, no credit card required\n\n### Server Endpoints\n\n- **MCP protocol**: `POST /mcp` - JSON-RPC 2.0 MCP endpoint\n- **Direct tool access**: `POST /mcp/{tool_name}` - Direct tool invocation\n- **[Health check](/health)**: `GET /health` - Server status verification\n- **[Docs (this page)](/docs)**: `GET /docs` - Server documentation\n- **[Change log](/changelog)**: `GET /changelog` - Release history and changes\n- **[Available data sources](/datasources)**: `GET /datasources` - Listing of data sources\n- **[OpenAPI 3.1.0](/openapi.json)**: `GET /openapi.json` - OpenAPI specification\n- **[Swagger 2.0](/swagger.json)**: `GET /swagger.json` - Swagger specification\n- **[LLM summary](/llms.txt)**: `GET /llms.txt` - Concise server summary for LLMs\n- **[LLM full reference](/llms-full.txt)**: `GET /llms-full.txt` - Complete reference for LLMs\n\n\n## Tool Descriptions\n\n### Data Source Discovery Tool (`data_source_discovery`)\n\nDiscover available data sources and their capabilities including supported metrics and dimensions.\n\n**Key Features:**\n- Complete data source catalog browsing\n- Capability assessment for each source\n- Integration requirement identification\n- Account type compatibility checking\n\n**Use Cases:**\n- Explore available integrations\n- Assess data source capabilities before setup\n- Plan multi-source reporting strategies\n- Validate account compatibility\n\n### Field Discovery Tool (`field_discovery`)\n\nExplore available fields, metrics, and dimensions for specific data sources with intelligent recommendations.\n\n**Key Features:**\n- Complete field catalog with descriptions\n- Field compatibility assessment\n- Custom field support detection\n\n**Use Cases:**\n- Design custom reports with appropriate fields\n- Understand available metrics before querying\n- Validate field availability for specific data sources\n\n### Account Discovery Tool (`accounts_discovery`)\n\nDiscover and validate connected accounts for specific data sources.\n\n**Key Features:**\n- Account discovery and validation\n- Credential verification\n- Account-specific capability assessment\n- Multi-account management support\n\n**Use Cases:**\n- Validate account connections\n- Discover available accounts for reporting\n- Troubleshoot account access issues\n- Manage account permissions and access\n\n### Data Query Tool (`data_query`)\n\nExecute asynchronous data queries against the Supermetrics API with comprehensive status monitoring.\n\n**Key Features:**\n- Real-time query progress tracking\n- Automatic retry logic for transient failures\n- Support for complex date ranges and filtering\n- Multi-account query support\n\n**Use Cases:**\n- Retrieve marketing performance data\n- Generate custom reports across multiple accounts\n- Export data for analysis and visualization\n- Monitor campaign metrics in real-time\n\n### Async Query Results Tool (`get_async_query_results`)\n\nRetrieve results of data queries using schedule_id for asynchronous data processing.\n\n**Key Features:**\n- Query result retrieval by schedule ID\n- Real-time status monitoring\n- Progress tracking for long-running queries\n- Automatic result formatting\n\n**Use Cases:**\n- Check completion status of async queries\n- Retrieve processed data results\n- Monitor query execution progress\n- Handle large dataset downloads\n\n### Get Today Tool (`get_today`)\n\nUtility tool providing current date information in various formats for query parameters.\n\n**Key Features:**\n- Multiple date format support\n- Timezone handling\n- Relative date calculations\n- Query parameter formatting\n\n**Use Cases:**\n- Generate dynamic date ranges for queries\n- Ensure consistent date formatting across requests\n- Handle timezone-specific reporting requirements\n\n### User Information Tool (`user_info`)\n\nRetrieve comprehensive user profile information including personal details, team information, and license status.\n\n**Key Features:**\n- Complete user profile data (name, email, user ID)\n- Team information and permissions\n- License details including status, expiration, and days remaining\n- Product information and subscription details\n- Account validation and authentication verification\n\n**Use Cases:**\n- Verify user authentication and account status\n- Check validity trial or paid license and expiration dates\n- Display user context information in applications\n- Monitor subscription status and renewal dates\n- Troubleshoot account access issues\n\n### Campaign & Resource Get Tool (`campaign_and_resource_get`) *(Beta)*\n\nGet campaign details, list campaigns, and explore related resources across Google Ads, Meta Ads, Microsoft Ads, TikTok Ads, and LinkedIn Ads.\n\n**Key Features:**\n- List campaigns with status filtering and detail levels (full, campaign, ad_group)\n- Campaign health checks with performance snapshots\n- Keyword research: idea generation and search volume lookups (Google Ads, Microsoft Ads)\n- Targeting catalog search and audience reach estimation\n- Asset library browsing (images, videos)\n- Audience discovery: interest, remarketing, and custom audiences\n- Optimization recommendations from the ad platform\n- Campaign change history and audit trail\n- Conversion action discovery\n\n**Use Cases:**\n- Review campaign structure and performance before making changes\n- Research keywords and audiences for new campaigns\n- Estimate audience reach for targeting configurations\n- Browse existing creative assets for reuse\n- Audit campaign change history\n\n### Create Campaign Tool (`campaign_create`) *(Beta)*\n\nCreate advertising campaigns across Google Ads, Meta Ads, Microsoft Ads, TikTok Ads, and LinkedIn Ads — including ad groups and ads in a single call.\n\n**Key Features:**\n- Full campaign creation with budget, targeting, bidding, and scheduling\n- Nested ad group and ad creation in one operation\n- Text ads (RSA), display ads, video ads, carousel ads, and lead form ads\n- AI image generation from text prompts\n- Ad extensions: sitelinks, structured snippets, images\n- Platform-specific settings for advanced configuration\n- Campaigns always created as PAUSED for safe review before launch\n\n**Use Cases:**\n- Spin up new campaigns from a brief or strategy document\n- Create multi-ad-group campaign structures in one step\n- Launch campaigns across multiple platforms with consistent settings\n- Generate ad creatives including AI-generated images\n\n### Update Campaign Tool (`campaign_update`) *(Beta)*\n\nUpdate existing campaigns — change status, budgets, targeting, ads, and more.\n\n**Key Features:**\n- Partial updates: only specified fields are changed\n- Enable, pause, or remove campaigns, ad groups, and ads\n- Update budgets, bidding strategies, and schedules\n- Replace targeting and ad extensions\n- Add new ad groups and ads to existing campaigns\n- Remove specific ads or ad groups by ID\n- Ad review status tracking (APPROVED, DISAPPROVED, IN_REVIEW)\n\n**Use Cases:**\n- Pause or enable campaigns based on performance\n- Adjust budgets and bidding strategies\n- Refresh ad copy and creatives\n- Add or remove ad groups as strategy evolves\n- Update targeting based on audience insights\n\n## Campaign Create/Update Actions\n\nTo create or modify campaigns, you need to enable write actions for the advertising accounts: [https://hub.supermetrics.com/write-settings](https://hub.supermetrics.com/write-settings)\nYou can see all the edit actions that have been done at [https://hub.supermetrics.com/campaign-history](https://hub.supermetrics.com/campaign-history)\n\n## Authentication\n\nSupermetrics MCP Server supports secure authentication through bearer tokens:\n\n### User Tokens (OAuth) - Recommended\nFormat: `Authorization: Bearer otok_*`\n- Use for user-specific authentication via OAuth flow\n- Required for `user_info` tool to access profile and license data\n- Access limited to user's account permissions\n- URLs:\n  - MCP server: https://mcp.supermetrics.com/mcp\n  - OAuth authorization: https://api.supermetrics.com/oauth/authorize\n  - OAuth token: https://api.supermetrics.com/oauth/token\n  - OAuth refresh: https://api.supermetrics.com/oauth/token\n- We support Dynamic Client Registration (DCR) and Client ID Metadata Document (CIMD) for OAuth applications.\n\n### API Keys\nFormat: `Authorization: Bearer api_*`\n- Use for server-to-server authentication\n- Requires valid Supermetrics API key\n- Provides full API access based on key permissions\n- You can create an API key at https://hub.supermetrics.com/api-key-management\n\n## Troubleshooting Guide\n\n### Common Setup Issues\n\n**Authentication Failures**\n- Verify API key format starts with `api_` or `otok_`\n- Check API key has necessary permissions in Supermetrics\n- Ensure Authorization header includes `Bearer` prefix\n- Validate token hasn't expired or been revoked\n\n### Tool Execution Issues\n\n**Data Query Failures**\n- Verify account permissions for requested data sources\n- Check date range parameters are valid\n- Ensure field names match data source schema\n- Review query complexity and rate limits\n\n**Field Discovery Problems**\n- Confirm data source ID is correct and supported\n- Check account has access to specified data source\n- Verify API credentials have field discovery permissions\n- Review data source documentation for field availability\n\n**Account Management Issues**\n- Validate account IDs exist and are accessible\n- Check account permissions match requested operations\n- Ensure credentials provide account management access\n- Verify account status in Supermetrics dashboard\n\n### Performance Issues\n\n**Slow Query Responses**\n- Review query complexity and data volume\n- Consider breaking large queries into smaller chunks\n- Check network connectivity to Supermetrics MCP Server\n\n**Timeout Errors**\n- Increase client timeout settings for large queries\n- Implement proper retry logic with exponential backoff\n\n### Getting Additional Help\n\n1. **API Documentation**: Review Supermetrics API documentation for endpoint details\n2. **Network Connectivity**: Test direct API connectivity to isolate network issues\n3. **Account Validation**: Verify account status and permissions in Supermetrics dashboard\n4. **Client Configuration**: Review MCP client setup and configuration files\n\nFor persistent issues, ensure your Supermetrics account has the necessary permissions and that all authentication\ncredentials are valid and current.\n\nFor customer support, please contact dev-rnd@supermetrics.com\n\n### Links\n\n- [Supermetrics Hub](https://hub.supermetrics.com/)\n- [Knowledge base and support](https://docs.supermetrics.com/)\n- [Data source documentation](https://docs.supermetrics.com/docs/connect)\n- [Terms of service and data processing agreement](https://supermetrics.com/terms-of-service)\n- [Privacy policy](https://supermetrics.com/privacy-policy)\n","last_updated":1777902701.0,"status":"publicly_accessible","api_specs":{"openapi":"/openapi.json","swagger":"/swagger.json"}}