skai-reports-mcp（skai reports MCP 搜索）

Skai Reports MCP

Overview

Skai is an AI-powered omnichannel marketing platform that unifies digital advertising across retail media (Amazon, Walmart, Target, Instacart), paid search (Google), and paid social (Meta, TikTok). The Reports MCP provides tools to query marketing performance data, investigate operational changes, and analyze competitive positioning.

Available Tools

Key Marketing Terms

Entity Types

All entity names are UPPERCASE:

CAMPAIGN, ADGROUP, KEYWORD, AD, PROFILE, PRODUCT_ASSET, SEARCH_TERM, CREATIVE_ASSET, COMPETITIVE_INSIGHTS, COMPETITIVE_INSIGHTS_KEYWORD_DRILLDOWN, SOV_SEARCH_TERM, NEGATIVE_KEYWORDS

PROFILE limitation: Does NOT support group_bys. Use CAMPAIGN entity if you need segmentation.

Core Workflow

1. relevant_columns(entity) -> discover exact column names and groups
2. fetch_report(entity, fields, date_range, ...) -> get data
3. Analyze, then fetch more if needed

Always call relevant_columns first to get exact column names and groups. Column names are PascalCase (e.g., CampaignName, Clicks, AverageCPC). Every column has a group (ATTRIBUTES, PERFORMANCE, TIME_SEGMENT, DIMENSIONS, etc.) that MUST be specified.

fetch_report Reference

Parameter Structure

{
  "entity": "CAMPAIGN",
  "date_range": {"start_date": "2025-10-07", "end_date": "2025-10-13"},
  "fields": [
    {"name": "CampaignName", "group": "ATTRIBUTES"},
    {"name": "Clicks", "group": "PERFORMANCE"},
    {"name": "Cost", "group": "PERFORMANCE"}
  ],
  "filters": [
    {"field": "ChannelName", "operator": "IN", "values": ["Amazon", "Google"], "group": "ATTRIBUTES"}
  ],
  "sort": {"field": "Clicks", "group": "PERFORMANCE", "order": "DESCENDING"},
  "breakdown_type": "FLAT",
  "limit": 20
}

Critical Rules

1. fields — Array of {name, group} objects. Max 100 columns. Use exact names from relevant_columns.
2. breakdown_type — Required. "FLAT" for flat data, "GROUP" when using group_bys.
3. group_bys — Array of {name, group} objects. Max 3. Requires breakdown_type: "GROUP".
4. filters — Array of {field, operator, values, group} objects. Operators: IN, EQUALS, NOT_EQUALS, GREATER_THAN, LESS_THAN, CONTAINS, etc.
5. sort — Object: {field, group, order}. Order: "ASCENDING" or "DESCENDING".
6. limit — Max 20,000 rows (default).

TIME_SEGMENT Rule

Time columns (DAY, Week, Month, Quarter, Year) MUST appear in BOTH fields AND group_bys:

{
  "fields": [{"name": "DAY", "group": "TIME_SEGMENT"}, ...],
  "group_bys": [{"name": "DAY", "group": "TIME_SEGMENT"}, ...],
  "breakdown_type": "GROUP"
}

Period-Over-Period Comparison

Use previous_date_range — do NOT make separate calls:

{
  "entity": "CAMPAIGN",
  "date_range": {"start_date": "2025-11-01", "end_date": "2025-11-30"},
  "previous_date_range": {"start_date": "2025-10-01", "end_date": "2025-10-31"},
  "fields": [
    {"name": "CampaignName", "group": "ATTRIBUTES"},
    {"name": "Revenue", "group": "PERFORMANCE"}
  ],
  "filters": [
    {"comparison_type": "PERCENTAGE_DELTA", "field": "Revenue", "group": "PERFORMANCE", "operator": "GREATER_THAN", "values": ["0.5"]}
  ],
  "sort": {"field": "Revenue", "group": "PERFORMANCE", "order": "DESCENDING", "comparison_type": "ABSOLUTE_DELTA"},
  "breakdown_type": "FLAT"
}

When previous_date_range is provided, these columns are auto-generated (do NOT request them in fields):

• <column>Previous — value from previous period
• <column>AbsoluteDelta — absolute difference
• <column>PercentageDelta — percentage change (as decimal, so 0.5 = 50%)

You can filter and sort on these using comparison_type: "PREVIOUS", "ABSOLUTE_DELTA", or "PERCENTAGE_DELTA".

Date Range Options

Explicit: {"start_date": "2025-01-01", "end_date": "2025-03-31"}

Preset: {"preset": "LAST_7_DAYS"} or {"preset": "THIS_MONTH", "as_of": "2025-06-15"}

Available presets: LAST_7_DAYS, THIS_MONTH, LAST_QUARTER, etc. Default if user doesn't specify a range: previous calendar week.

Composite Filters (PRODUCT_ASSET only)

Products lack direct relationship columns. Use compositeFilters to link products to other entities:

{
  "compositeFilters": [
    {
      "entity": "PRODUCT_ASSET",
      "type": "ANY_MATCH",
      "filters": [
        {"field": "Product Id", "operator": "EQUALS", "values": ["5678"], "group": "PRODUCT_IDENTIFIERS"}
      ]
    }
  ]
}

Response Structure

fetch_report returns:

• records — List of data rows (limited by limit). May be partial.
• summary — Aggregation across ALL matching entities (not just visible records).
• total — Total entity count matching filters. Use this for counts, never count visible records.
• CSV download URL — Pre-signed S3 URL (expires 30 min).

get_change_log Reference

Queries Snowflake for operational changes. Supported entities: campaign, adGroup, keyword, ad (lowercase).

Filterable fields: daily_budget, budget, bid_adjustment, desktop_bid_adjustment, tablet_bid_adjustment, mobile_bid_adjustment, placements, name, status, cpa_goal.

Change operators: ADD, REMOVE, MODIFY, BID_CHANGES, UPLOAD, etc.

Returns: timestamp, username (who made change), entity details, field changes with old/new values. Default 500 rows, max 1000. Set exclude_noisy_fields=False to include sync/update noise.

get_competitive_context Reference

Must call before using COMPETITIVE_INSIGHTS entities. Returns client brands ("my brands") and competitor brand mappings per publisher.

After getting context, use the brand names to filter COMPETITIVE_INSIGHTS or COMPETITIVE_INSIGHTS_KEYWORD_DRILLDOWN entities in fetch_report.

• COMPETITIVE_INSIGHTS — Brand-level share of voice (SOV). Always use breakdown_type: "GROUP", default sort by SovAndPos, default filter PageSection="FULL_PAGE".
• COMPETITIVE_INSIGHTS_KEYWORD_DRILLDOWN — Product-level SOV within keywords. Despite the name, shows products not keywords. Always group by AsinAndMarketplace.
• SOV_SEARCH_TERM — Lists keywords/search terms used in CI. No performance data.

Best Practices

1. Always start with relevant_columns to discover exact column names and groups. Never guess column names.
2. Use previous_date_range for comparisons — don't make separate calls and calculate manually.
3. Use group_bys instead of fetching flat data and aggregating yourself.
4. Use summary and total from response for aggregate counts — records may be partial due to limits.
5. Prefer fetching more data over calculating from existing partial data.
6. Parallel tool calls — when fetching multiple independent reports, call them simultaneously.
7. Names verbatim — display entity names exactly as returned, without abbreviation.
8. Empty results — when filtering returns records: [], filters are too restrictive, not missing activity. Ask user to verify filter values. Do NOT suggest trying different time periods.
9. Date handling — always use ISO 8601 (YYYY-MM-DD). Convert user terms (e.g., "Q2 2025" = 2025-04-01 to 2025-06-30). Default to previous calendar week if unspecified.

Common Mistakes