Supermetrics MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your Supermetrics MCP credentials with Scalekit so it handles the token lifecycle. You do this once per environment.

   Dashboard setup steps

   Supermetrics MCP uses Dynamic Client Registration (DCR) — no client ID or secret is required. The only step is creating a connection in Scalekit and authorizing your Supermetrics account.

   1. Create a connection in Scalekit

      • In the Scalekit dashboard, go to AgentKit → Connections → Create Connection.
      • Search for Supermetrics MCP and click Create.
      • Note the Connection name — use this as connection_name in your code (e.g., supermetricsmcp).

   2. Authorize your Supermetrics account

      Generate an authorization link and open it in a browser to complete the Supermetrics OAuth flow.

      The user is redirected to Supermetrics to sign in and grant access. Scalekit stores the token and injects it automatically into every tool call — no further configuration is needed.

      Connected data sources required

      The user must have an active Supermetrics subscription with at least one data source connected. Use data_source_discovery after connecting to list available sources, and accounts_discovery to find the ad account IDs available for querying.

4. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'supermetricsmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Supermetrics MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'supermetricsmcp_get_today',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "supermetricsmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Supermetrics MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="supermetricsmcp_get_today",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Info user — Retrieve the authenticated Supermetrics user’s profile information
• Manage resources — Open the visual media picker or manage ad creative assets for a supported platform
• Get today, async query results, campaign and resource — Get the current UTC date and time
• Discovery field, data source, accounts — List available metrics and dimensions for a specific data source
• Query data — Query marketing analytics data from any connected data source, with optional date ranges, field selection, and filters
• Supermetrics contact — Send product feedback, create a support ticket, or submit a sales enquiry to Supermetrics

Common workflows

Discover available data sources

Use supermetricsmcp_data_source_discovery to list all marketing and advertising data sources connected to the user’s Supermetrics account.

Node.js

const sources = await actions.executeTool({
  connectionName: 'supermetricsmcp',
  identifier: 'user_123',
  toolName: 'supermetricsmcp_data_source_discovery',
  toolInput: {},
});
console.log(sources);

Python

sources = actions.execute_tool(
    connection_name="supermetricsmcp",
    identifier="user_123",
    tool_name="supermetricsmcp_data_source_discovery",
    tool_input={},
)
print(sources)

Query marketing analytics data

Use supermetricsmcp_data_query to pull structured metrics and dimensions from a connected data source. Call field_discovery first to find valid field names, and get_today to resolve relative date references.

Node.js

const report = await actions.executeTool({
  connectionName: 'supermetricsmcp',
  identifier: 'user_123',
  toolName: 'supermetricsmcp_data_query',
  toolInput: {
    ds_id: 'GA4',
    fields: ['Sessions', 'Conversions', 'Date'],
    date_range_type: 'last_30_days',
    max_rows: 100,
  },
});
console.log(report);

Python

report = actions.execute_tool(
    connection_name="supermetricsmcp",
    identifier="user_123",
    tool_name="supermetricsmcp_data_query",
    tool_input={
        "ds_id": "GA4",
        "fields": ["Sessions", "Conversions", "Date"],
        "date_range_type": "last_30_days",
        "max_rows": 100,
    },
)
print(report)

Create an ad campaign

Use supermetricsmcp_campaign_create to create a new advertising campaign on a supported platform. Call accounts_discovery first to find the correct account ID.

Node.js

const campaign = await actions.executeTool({
  connectionName: 'supermetricsmcp',
  identifier: 'user_123',
  toolName: 'supermetricsmcp_campaign_create',
  toolInput: {
    ds_id: 'FA',
    account_id: 'act_123456789',
    name: 'Q1 Brand Awareness',
    status: 'PAUSED',
    budget_amount: '50.00',
    budget_type: 'DAILY',
  },
});
console.log(campaign);

Python

campaign = actions.execute_tool(
    connection_name="supermetricsmcp",
    identifier="user_123",
    tool_name="supermetricsmcp_campaign_create",
    tool_input={
        "ds_id": "FA",
        "account_id": "act_123456789",
        "name": "Q1 Brand Awareness",
        "status": "PAUSED",
        "budget_amount": "50.00",
        "budget_type": "DAILY",
    },
)
print(campaign)

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

supermetricsmcp_accounts_discovery#List connected ad accounts and profiles for a marketing or advertising data source.3 params▾

List connected ad accounts and profiles for a marketing or advertising data source.

NameTypeRequiredDescription

ds_idstringrequiredData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

compressstringoptionalWhether to compress the response payload.

filterstringoptionalText filter to narrow discovery results.

supermetricsmcp_campaign_and_resource_get#Retrieve campaign details, performance metrics, or related resources from an advertising platform.5 params▾

Retrieve campaign details, performance metrics, or related resources from an advertising platform.

NameTypeRequiredDescription

account_idstringrequiredAd account or profile ID for the selected data source.

ds_idstringrequiredData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

max_rowsstringoptionalMaximum number of rows to return.

paramsstringoptionalResource-type-specific parameters. See ResourceParams for which fields apply to each resource_type.

resource_typestringoptionalType of resource to retrieve (e.g. `CAMPAIGN`, `AD_GROUP`).

supermetricsmcp_campaign_create#Create a new advertising campaign on Google Ads, Facebook Ads, TikTok Ads, LinkedIn Ads, or Microsoft Advertising.14 params▾

Create a new advertising campaign on Google Ads, Facebook Ads, TikTok Ads, LinkedIn Ads, or Microsoft Advertising.

NameTypeRequiredDescription

account_idstringrequiredAd account or profile ID for the selected data source.

ds_idstringrequiredData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

namestringrequiredDisplay name for the campaign.

ad_groupsstringoptionalAd groups (AW/AC) or ad sets (FA/TIK) to create with the campaign.

bidding_strategystringoptionalBidding strategy. Also accepted inside platform_settings. AW: MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CONVERSION_VALUE, TARGET_ROAS. For TARGET_ROAS, set the target value via platform_settings.bidding_config.target_roas (float multiplier, e.g. 3.5 = 350% ROAS). Without it, optimizes for max value with no target. For TARGET_CPA, set target via platform_settings.bidding_config.target_cpa (float in account currency, e.g. 5.0 = $5). AC: MAX_CLICKS, MAX_CONVERSIONS, MANUAL_CPC, ENHANCED_CPC, TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSION_VALUE. FA: LOWEST_COST_WITHOUT_CAP (default), LOWEST_COST_WITH_BID_CAP, COST_CAP. FA also accepts TARGET_ROAS — use bidding_config.target_roas to set the target. Auto-sets OUTCOME_SALES objective, VALUE optimization, and pixel if not specified.

budget_amountstringoptionalDaily or lifetime budget amount in the account currency.

budget_typestringoptionalBudget type: DAILY or LIFETIME. LIA: only LIFETIME at campaign level. AC: LIFETIME only works on AUDIENCE campaigns.

end_datestringoptionalEnd of the data range (YYYY-MM-DD).

extensionsstringoptionalAd extensions (AW/AC — sitelinks, callouts, snippets; AW also supports image extensions). Ignored on FA/TIK.

platform_settingsstringoptionalPlatform-specific settings. AW: {campaign_type (SEARCH, DISPLAY, PERFORMANCE_MAX, SHOPPING, VIDEO, DEMAND_GEN), bidding_strategy, bidding_config (see below), network_settings}. bidding_config (AW/AC/FA): {target_roas (float multiplier, e.g. 3.5 = 350% ROAS — used with TARGET_ROAS), target_cpa (float in account currency, e.g. 5.0 = $5 — used with TARGET_CPA)}. Works the same on all platforms. AC: {campaign_type (SEARCH, AUDIENCE, SHOPPING, DYNAMIC_SEARCH, PERFORMANCE_MAX), bidding_strategy (MAX_CLICKS, MAX_CONVERSIONS, MANUAL_CPC, TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSION_VALUE, ENHANCED_CPC)}. FA: {objective (OUTCOME_TRAFFIC, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_AWARENESS, OUTCOME_APP_PROMOTION), special_ad_categories, buying_type, campaign_budget_optimization (true=CBO on, budget at campaign level; false=CBO off, budget per ad set)}. TIK: {objective_type (TRAFFIC, LEAD_GENERATION, REACH, VIDEO_VIEWS, CONVERSIONS, APP_INSTALL), promotion_type (WEBSITE, APP, SHOP — defaults to WEBSITE), placement_type (PLACEMENT_TYPE_AUTOMATIC default)}.LIA: campaign-level platform_settings are optional. Ad group platform_settings are where LIA-specific options go (campaign_type, cost_type, objective_type, daily_budget).

start_datestringoptionalStart of the data range (YYYY-MM-DD).

statusstringoptionalCampaign status (e.g. `ENABLED`, `PAUSED`).

targetingstringoptionalCampaign-level targeting defaults inherited by all ad groups

url_tagsstringoptionalCampaign-level URL tracking parameters appended to ad links

supermetricsmcp_campaign_update#Update an existing advertising campaign by its ID on a supported ad platform.17 params▾

Update an existing advertising campaign by its ID on a supported ad platform.

NameTypeRequiredDescription

account_idstringrequiredAd account or profile ID for the selected data source.

campaign_idstringrequiredUnique identifier of the campaign to update.

ds_idstringrequiredData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

ad_groupsstringoptionalAd groups to create (no id) or update (with id). Only provided fields change on update.

bidding_strategystringoptionalNew bidding strategy. AW: MANUAL_CPC, MAXIMIZE_CLICKS, MAXIMIZE_CONVERSIONS, TARGET_CPA, MAXIMIZE_CONVERSION_VALUE, TARGET_ROAS. For TARGET_ROAS, set the target value via platform_settings.bidding_config.target_roas (float multiplier, e.g. 3.5 = 350% ROAS). Without it, optimizes for max value with no target. For TARGET_CPA, set target via platform_settings.bidding_config.target_cpa (float in account currency, e.g. 5.0 = $5). AC: MAX_CLICKS, MAX_CONVERSIONS, MANUAL_CPC, ENHANCED_CPC, TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSION_VALUE. FA: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP. FA also accepts TARGET_ROAS — use bidding_config.target_roas to set the target. IMPORTANT: FA bid strategy changes require the campaign to have a budget. CBO-off campaigns (budget at ad set level) cannot have their bid strategy changed. LOWEST_COST_WITH_BID_CAP requires bid_amount on each ad set.

budget_amountstringoptionalDaily or lifetime budget amount in the account currency.

budget_typestringoptionalNew budget type: DAILY or LIFETIME. LIA: only LIFETIME at campaign level. AC: LIFETIME only works on AUDIENCE campaigns.

end_datestringoptionalEnd of the data range (YYYY-MM-DD).

extensionsstringoptionalReplace extensions (removes old, adds new) — AW/AC. Ignored on FA/TIK.

namestringoptionalDisplay name for the campaign.

platform_settingsstringoptionalPlatform-specific settings to update. AW/AC/FA: {bidding_config: {target_roas (float, e.g. 3.5 = 350%), target_cpa (float, e.g. 5.0 = $5)}}. AW: {ad_schedule, bid_adjustments}. FA: {campaign_budget_optimization (true=CBO on, false=CBO off)}.

remove_ad_group_idsstringoptionalAd group / ad set IDs to remove

remove_ad_idsstringoptionalAd IDs to remove

start_datestringoptionalStart of the data range (YYYY-MM-DD).

statusstringoptionalCampaign status (e.g. `ENABLED`, `PAUSED`).

targetingstringoptionalReplace campaign targeting (removes old, adds new)

url_tagsstringoptionalCampaign-level URL tracking parameters appended to ad links

supermetricsmcp_contact_supermetrics#Send product feedback, create a support ticket, or submit a sales enquiry to Supermetrics.10 params▾

Send product feedback, create a support ticket, or submit a sales enquiry to Supermetrics.

NameTypeRequiredDescription

messagestringrequiredDetailed description. Include relevant context: tools used, errors encountered, data sources involved, trace IDs

subjectstringrequiredBrief summary of the feedback or issue

typestringrequiredType of contact: 'feedback' for product feedback/feature requests, 'support' for technical issues, 'sales' for sales enquiries and demo requests

categorystringoptionalSupport ticket category. Only used when type is 'support'

companystringoptionalContact's company name. Required when type is 'sales'

countrystringoptionalContact's country. Required when type is 'sales'

ds_idstringoptionalData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

firstnamestringoptionalContact's first name. Required when type is 'sales'

industrystringoptionalContact's industry. Used when type is 'sales'

lastnamestringoptionalContact's last name. Required when type is 'sales'

supermetricsmcp_data_query#Query marketing analytics data from any connected data source, with optional date ranges, field selection, and filters.14 params▾

Query marketing analytics data from any connected data source, with optional date ranges, field selection, and filters.

NameTypeRequiredDescription

ds_idstringrequiredData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

compare_end_datestringoptionalEnd of the comparison period (YYYY-MM-DD). Required when `compare_type` is `custom`.

compare_showstringoptionalHow to display the comparison: - 'perc_change': percentage change (default) - 'abs_change': absolute change - 'value': raw value from the comparison period

compare_start_datestringoptionalStart of the comparison period (YYYY-MM-DD). Required when `compare_type` is `custom`.

compare_typestringoptionalSelect how to compare results to an earlier period: - 'prev_range': previous period of the same length - 'prev_year': same period in the previous year - 'prev_year_weekday': same weekdays in the previous year - 'custom': user-defined period (requires compare_start_date and compare_end_date)

date_range_typestringoptionalPreset date range (e.g. `last_30_days`, `last_month`). Use instead of `start_date`/`end_date`.

ds_accountsstringoptionalList of account IDs to query data from.

end_datestringoptionalEnd of the data range (YYYY-MM-DD).

fieldsstringoptionalList of metric and dimension field names to include. Use `field_discovery` to find valid field names.

filtersstringoptionalList of field filters to narrow the query results.

max_rowsstringoptionalMaximum number of rows to return.

settingsstringoptionalAll data source-specific settings from data_source_discovery config mode. Pass as a JSON object. IMPORTANT: Every setting_id from data_source_discovery (report_type, common_settings, report-type-specific settings) MUST be passed inside this object — do NOT pass them as separate root-level parameters. Example: {"report_type": "TopIosApps", "country": "US", "list_type": "top-free"}

start_datestringoptionalStart of the data range (YYYY-MM-DD).

timezonestringoptionalTimezone for date calculations (e.g. `America/New_York`).

supermetricsmcp_data_source_discovery#List all available marketing and advertising data sources supported by Supermetrics.2 params▾

List all available marketing and advertising data sources supported by Supermetrics.

NameTypeRequiredDescription

compressstringoptionalWhether to compress the response payload.

ds_idstringoptionalData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

supermetricsmcp_field_discovery#List available metrics and dimensions for a specific data source. Returns field names usable in `data_query`.3 params▾

List available metrics and dimensions for a specific data source. Returns field names usable in `data_query`.

NameTypeRequiredDescription

ds_idstringrequiredData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

compressstringoptionalWhether to compress the response payload.

filterstringoptionalText filter to narrow discovery results.

supermetricsmcp_get_async_query_results#Retrieve results of an async `data_query` using the schedule ID returned by that query.2 params▾

Retrieve results of an async `data_query` using the schedule ID returned by that query.

NameTypeRequiredDescription

schedule_idstringrequiredSchedule ID returned by `data_query` for async result retrieval.

compressstringoptionalWhether to compress the response payload.

supermetricsmcp_get_today#Get the current UTC date and time. Use before `data_query` to resolve relative date references.0 params▾

Get the current UTC date and time. Use before `data_query` to resolve relative date references.

supermetricsmcp_resources_manage#Open the visual media picker or manage ad creative assets for a supported platform.5 params▾

Open the visual media picker or manage ad creative assets for a supported platform.

NameTypeRequiredDescription

account_idstringrequiredAd account or profile ID for the selected data source.

ds_idstringrequiredData source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

actionstringoptionalAction to perform on the resource (e.g. `browse_assets`).

asset_typestringoptionalType of creative asset to manage (e.g. `IMAGE`, `VIDEO`).

paramsstringoptionalInternal action-specific parameters (used by the picker UI).

supermetricsmcp_user_info#Retrieve the authenticated Supermetrics user's profile information.0 params▾

Retrieve the authenticated Supermetrics user's profile information.