Supermetrics MCP connector

OAuth 2.1/DCR MarketingAnalyticsCRM & Sales

Connect to Supermetrics MCP to query marketing data, discover data sources, manage campaigns, and run analytics across your connected ad and analytics...

Supermetrics MCP connector

Install the SDK
Section titled “Install the SDK”
- Node.js
- Python
Terminal window
1 npm install @scalekit-sdk/node
Terminal window
1 pip install scalekit
Full SDK reference: Node.js | Python
Set your credentials
Section titled “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>
```
Set up the connector
Section titled “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.
  
  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.

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3

4
const scalekit = new ScalekitClient(
5
  process.env.SCALEKIT_ENV_URL,
6
  process.env.SCALEKIT_CLIENT_ID,
7
  process.env.SCALEKIT_CLIENT_SECRET,
8
)
9
const actions = scalekit.actions
10

11
const connector = 'supermetricsmcp'
12
const identifier = 'user_123'
13

14
// Generate an authorization link for the user
15
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
16
console.log('Authorize Supermetrics MCP:', link)
17
process.stdout.write('Press Enter after authorizing...')
18
await new Promise(r => process.stdin.once('data', r))
19

20
// Make your first call
21
const result = await actions.executeTool({
22
  connector,
23
  identifier,
24
  toolName: 'supermetricsmcp_get_today',
25
  toolInput: {},
26
})
27
console.log(result)

1
import os
2
from scalekit.client import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENV_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "supermetricsmcp"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Supermetrics MCP:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="supermetricsmcp_get_today",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
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
Python

1
const sources = await actions.executeTool({
2
  connectionName: 'supermetricsmcp',
3
  identifier: 'user_123',
4
  toolName: 'supermetricsmcp_data_source_discovery',
5
  toolInput: {},
6
});
7
console.log(sources);

1
sources = actions.execute_tool(
2
    connection_name="supermetricsmcp",
3
    identifier="user_123",
4
    tool_name="supermetricsmcp_data_source_discovery",
5
    tool_input={},
6
)
7
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
Python

1
const report = await actions.executeTool({
2
  connectionName: 'supermetricsmcp',
3
  identifier: 'user_123',
4
  toolName: 'supermetricsmcp_data_query',
5
  toolInput: {
6
    ds_id: 'GA4',
7
    fields: ['Sessions', 'Conversions', 'Date'],
8
    date_range_type: 'last_30_days',
9
    max_rows: 100,
10
  },
11
});
12
console.log(report);

1
report = actions.execute_tool(
2
    connection_name="supermetricsmcp",
3
    identifier="user_123",
4
    tool_name="supermetricsmcp_data_query",
5
    tool_input={
6
        "ds_id": "GA4",
7
        "fields": ["Sessions", "Conversions", "Date"],
8
        "date_range_type": "last_30_days",
9
        "max_rows": 100,
10
    },
11
)
12
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
Python

1
const campaign = await actions.executeTool({
2
  connectionName: 'supermetricsmcp',
3
  identifier: 'user_123',
4
  toolName: 'supermetricsmcp_campaign_create',
5
  toolInput: {
6
    ds_id: 'FA',
7
    account_id: 'act_123456789',
8
    name: 'Q1 Brand Awareness',
9
    status: 'PAUSED',
10
    budget_amount: '50.00',
11
    budget_type: 'DAILY',
12
  },
13
});
14
console.log(campaign);

1
campaign = actions.execute_tool(
2
    connection_name="supermetricsmcp",
3
    identifier="user_123",
4
    tool_name="supermetricsmcp_campaign_create",
5
    tool_input={
6
        "ds_id": "FA",
7
        "account_id": "act_123456789",
8
        "name": "Q1 Brand Awareness",
9
        "status": "PAUSED",
10
        "budget_amount": "50.00",
11
        "budget_type": "DAILY",
12
    },
13
)
14
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.

Name Type Required Description

ds_id string required Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

compress string optional Whether to compress the response payload.

filter string optional Text 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.

Name Type Required Description

account_id string required Ad account or profile ID for the selected data source.

ds_id string required Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

max_rows string optional Maximum number of rows to return.

params string optional Resource-type-specific parameters. See ResourceParams for which fields apply to each resource_type.

resource_type string optional Type 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.

Name Type Required Description

account_id string required Ad account or profile ID for the selected data source.

ds_id string required Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

name string required Display name for the campaign.

ad_groups string optional Ad groups (AW/AC) or ad sets (FA/TIK) to create with the campaign.

bidding_strategy string optional Bidding 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_amount string optional Daily or lifetime budget amount in the account currency.

budget_type string optional Budget type: DAILY or LIFETIME. LIA: only LIFETIME at campaign level. AC: LIFETIME only works on AUDIENCE campaigns.

end_date string optional End of the data range (YYYY-MM-DD).

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

platform_settings string optional Platform-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_date string optional Start of the data range (YYYY-MM-DD).

status string optional Campaign status (e.g. `ENABLED`, `PAUSED`).

targeting string optional Campaign-level targeting defaults inherited by all ad groups

url_tags string optional Campaign-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.

Name Type Required Description

account_id string required Ad account or profile ID for the selected data source.

campaign_id string required Unique identifier of the campaign to update.

ds_id string required Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

ad_groups string optional Ad groups to create (no id) or update (with id). Only provided fields change on update.

bidding_strategy string optional New 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_amount string optional Daily or lifetime budget amount in the account currency.

budget_type string optional New budget type: DAILY or LIFETIME. LIA: only LIFETIME at campaign level. AC: LIFETIME only works on AUDIENCE campaigns.

end_date string optional End of the data range (YYYY-MM-DD).

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

name string optional Display name for the campaign.

platform_settings string optional Platform-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_ids string optional Ad group / ad set IDs to remove

remove_ad_ids string optional Ad IDs to remove

start_date string optional Start of the data range (YYYY-MM-DD).

status string optional Campaign status (e.g. `ENABLED`, `PAUSED`).

targeting string optional Replace campaign targeting (removes old, adds new)

url_tags string optional Campaign-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.

Name Type Required Description

message string required Detailed description. Include relevant context: tools used, errors encountered, data sources involved, trace IDs

subject string required Brief summary of the feedback or issue

type string required Type of contact: 'feedback' for product feedback/feature requests, 'support' for technical issues, 'sales' for sales enquiries and demo requests

category string optional Support ticket category. Only used when type is 'support'

company string optional Contact's company name. Required when type is 'sales'

country string optional Contact's country. Required when type is 'sales'

ds_id string optional Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

firstname string optional Contact's first name. Required when type is 'sales'

industry string optional Contact's industry. Used when type is 'sales'

lastname string optional Contact'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.

Name Type Required Description

ds_id string required Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

compare_end_date string optional End of the comparison period (YYYY-MM-DD). Required when `compare_type` is `custom`.

compare_show string optional How to display the comparison: - 'perc_change': percentage change (default) - 'abs_change': absolute change - 'value': raw value from the comparison period

compare_start_date string optional Start of the comparison period (YYYY-MM-DD). Required when `compare_type` is `custom`.

compare_type string optional Select 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_type string optional Preset date range (e.g. `last_30_days`, `last_month`). Use instead of `start_date`/`end_date`.

ds_accounts string optional List of account IDs to query data from.

end_date string optional End of the data range (YYYY-MM-DD).

fields string optional List of metric and dimension field names to include. Use `field_discovery` to find valid field names.

filters string optional List of field filters to narrow the query results.

max_rows string optional Maximum number of rows to return.

settings string optional All 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_date string optional Start of the data range (YYYY-MM-DD).

timezone string optional Timezone 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.

Name Type Required Description

compress string optional Whether to compress the response payload.

ds_id string optional Data 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`.

Name Type Required Description

ds_id string required Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

compress string optional Whether to compress the response payload.

filter string optional Text 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.

Name Type Required Description

schedule_id string required Schedule ID returned by `data_query` for async result retrieval.

compress string optional Whether 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.

Name Type Required Description

account_id string required Ad account or profile ID for the selected data source.

ds_id string required Data source identifier (e.g. `GA4`, `FA`, `ADWORDS`). Use `data_source_discovery` to list available IDs.

action string optional Action to perform on the resource (e.g. `browse_assets`).

asset_type string optional Type of creative asset to manage (e.g. `IMAGE`, `VIDEO`).

params string optional Internal 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.

Supermetrics MCP connector

Supermetrics MCP connector

Install the SDK

Set your credentials

Set up the connector

Create a connection in Scalekit

Authorize your Supermetrics account

Authorize and make your first call

What you can do

Common workflows

Discover available data sources

Query marketing analytics data

Create an ad campaign

Tool list