Creative Tagger MCP Server

The MCP layer for Creative Tagger — plug structured creative intelligence into any AI agent (Claude Desktop, Cursor, Windsurf, ChatGPT with MCP, etc.).

Release note (2026-08-30): this source tree and its packaged metadata are version 0.2.5. The hosted and stdio surfaces are separate clients of the same API and may expose different tool counts. The companion API must be deployed and live before this stdio release is tagged and published.

Your AI of choice gets:

• Taxonomy — 21 standardized dimensions for any ad creative (video, image, carousel, landing page, long video, email)

• Memory — every analysis is saved to the user's library; the agent can search it, recall patterns, and pull individual results

• Brand-custom taxonomy — extend the standard taxonomy with each brand's founders, products, segments, aliases, and naming variables

• Meta performance memory — read-only Meta sync/status/tools so agents can reason over objective-aware results, unproven tags, observational demographic delivery, and taxonomy gaps

• Brain learnings — auto-written account learnings in plain language, with agent-ready context for the next brief

• Strategist — recommendation + gap-analysis tools that reason over the user's library plus saved brand context (voice, audience, anti-patterns)

• Competitive intelligence — scan a competitor's Meta Ad Library through Creative Tagger's native Market access

Quick Start

The hosted server speaks standard MCP OAuth (dynamic client registration, PKCE) at https://api.creativetagger.ai/mcp/. Point your client at that URL and sign in when prompted:

• Claude Code — claude mcp add --transport http creative-tagger https://api.creativetagger.ai/mcp/ then claude mcp login creative-tagger (or run /mcp inside a session).

• Codex CLI / IDE — codex mcp add creative-tagger --url https://api.creativetagger.ai/mcp/ then codex mcp login creative-tagger.

• claude.ai (web/desktop/mobile) — Settings → Connectors → Add custom connector → paste https://api.creativetagger.ai/mcp/ → Connect.

• ChatGPT — Settings → Connectors → Advanced → Developer mode → add https://api.creativetagger.ai/mcp/.

• Other MCP clients (Cursor, VS Code, Gemini CLI, Windsurf, Hermes, etc.) — add the URL to the client's MCP config; the client's own OAuth prompt fires on first use.

Manage or revoke connected assistants any time under Settings → Connections.

For clients that don't do OAuth discovery (e.g. Grok's custom-connector integration), fall back to a bearer API key:

URL: https://api.creativetagger.ai/mcp/
Authorization: Bearer ct_your_key

The repository package is the stdio path for clients that require a local command. 0.2.5 is unreleased; install 0.2.4, the latest version on PyPI. Tools and options listed under 0.2.5 in CHANGELOG.md are not in 0.2.4:

# Install the latest published release (0.2.5 is not on PyPI yet)
pip install creative-tagger-mcp==0.2.4

# Run against production (default)
CREATIVE_TAGGER_API_KEY=ct_your_key creative-tagger-mcp

# Or against a local API
CREATIVE_TAGGER_URL=http://localhost:8000 \
CREATIVE_TAGGER_API_KEY=ct_your_key \
  creative-tagger-mcp

Get an API key at app.creativetagger.ai.

Related MCP server: muze-mcp

Release Verification

Before publishing a new MCP version, build the artifacts and smoke-test the wheel that will be uploaded to PyPI:

python -m build
python scripts/smoke_release.py
python -m twine check \
  dist/creative_tagger_mcp-0.2.5-py3-none-any.whl \
  dist/creative_tagger_mcp-0.2.5.tar.gz

The smoke test installs the wheel into a temporary virtualenv, verifies the creative-tagger-mcp console entry point, checks the package version, and confirms the V1 tool surface is present from the installed artifact.

Publishing to PyPI

The release workflow publishes from GitHub Actions after it builds the package, runs scripts/smoke_release.py, and passes twine check.

After the 0.2.5 review and API-dependency gates pass, tag the exact current main commit:

git tag -a v0.2.5 -m "Creative Tagger MCP v0.2.5"
git push origin refs/tags/v0.2.5

The workflow supports PyPI trusted publishing with GitHub OIDC. Configure the PyPI publisher for repository stephenlavender/creative-tagger-mcp, workflow .github/workflows/publish.yml, environment pypi, then push the version tag.

Exact PyPI trusted publisher values:

• PyPI project: creative-tagger-mcp

• Publisher: GitHub

• Owner: stephenlavender

• Repository: creative-tagger-mcp

• Workflow filename: publish.yml

• Environment name: pypi

If the workflow fails with invalid-publisher, PyPI does not have a trusted publisher matching those claims yet. Add the publisher above, then rerun the failed workflow or push the version tag again.

Fallback path: add a GitHub Actions repository secret named PYPI_API_TOKEN containing a PyPI project token. The same workflow will use that token when it is present.

Local fallback:

python -m build
python scripts/smoke_release.py
python -m twine check \
  dist/creative_tagger_mcp-0.2.5-py3-none-any.whl \
  dist/creative_tagger_mcp-0.2.5.tar.gz
python -m twine upload \
  dist/creative_tagger_mcp-0.2.5-py3-none-any.whl \
  dist/creative_tagger_mcp-0.2.5.tar.gz

Always select the exact release artifacts for a local upload. A reused checkout may contain older valid distributions in dist/; never publish with twine upload dist/*.

Add to Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "creative-tagger": {
      "command": "creative-tagger-mcp",
      "env": {
        "CREATIVE_TAGGER_URL": "https://api.creativetagger.ai",
        "CREATIVE_TAGGER_API_KEY": "ct_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The tools appear in the MCP picker.

Tools

analyze_creative

Analyze any ad creative and get structured classification across 21 dimensions.

{ "file_path": "./ad.mp4", "brand_name": "Brand" }
{ "url": "https://example.com/landing-page", "brand_name": "Brand" }
{ "html_content": "<html>...</html>", "brand_name": "Brand" }

Results auto-save to the user's library.

get_taxonomy

Read taxonomy v2's versioned vocabulary or one dimension. The package returns 15 controlled dimensions, one derived/open aspect_ratio dimension, and two intentionally dynamic, brand-specific dimensions. Aspect ratio includes common canonical examples but sets allow_other_values: true: the API may derive any reduced WxH ratio (such as 3x2 or 300x157) or preserve a W:H ratio for long video. The package does not infer enums from OpenAPI: several valid classification fields are strings in that schema, so schema discovery would silently return an incomplete taxonomy.

{}                                # all controlled + derived/open + dynamic dimensions
{ "dimension": "hook_type" }      # one dimension
{ "dimension": "aspect_ratio" }   # examples; other derived values remain valid

Taxonomy v2 splits three dimensions the old model mixed together: media type (the auto-detected format — static image, video, carousel; never AI-classified), asset type (production class: UGC, Studio, High Production, …), and visual format (execution style: Talking Head, Demo, Testimonial, …). Static Image and Carousel are media types and are no longer valid visual_format values. messaging_angle is the canonical angle dimension.

list_workspaces

List the authenticated user's available workspaces. Start every connected account workflow here, select one returned brand_name, and pass that exact value to every library, Meta status, report, and strategist call. Do not blend observations across workspaces unless the user explicitly requests a comparison.

{}

list_library

Browse saved analyses. Search by filename or hook, filter by format, messaging angle, emotion, CTA, talent, offer, audio type, or seasonality, and sort by joined performance. limit is clamped to 1–100 and offset to zero or higher before the request leaves the local stdio server.

{
  "brand_name": "Acme",
  "limit": 50,
  "search": "BFCM",
  "format": "video",
  "angle": "Social Proof",
  "talent": "Founder",
  "sort": "roas"
}

get_library_patterns

Cross-library pattern insights — concentration and diversity per dimension, plus rule-based diversification flags. Pass the exact workspace brand_name returned by list_workspaces.

get_analysis

Pull the full 21-dimension result for one library item.

{ "brand_name": "Acme", "analysis_id": 42 }

recommend ⭐

Ask the Creative Strategist a question grounded in the user's library + brand context.

{ "brand_name": "Acme", "question": "What kind of UGC should I test for Q4?" }

Returns concrete recommendations using taxonomy values + library observations.

analyze_gaps ⭐

Identify concentration risk in the library and propose next creatives that diversify it.

{ "brand_name": "Acme" }

get_brand_context / set_brand_context

Long-term memory per brand. Voice, target audience, top performers, anti-patterns, notes. set_brand_context is a partial update: omitted fields stay unchanged, while an explicit empty string or list clears only that field.

set_brand_context: {
  "brand_name": "Acme",
  "voice": "clinical, precise, no personality",
  "target_audience": "new moms 28-40, postpartum recovery",
  "top_performers": ["UGC TalkHead", "BeforeAfter visuals"],
  "anti_patterns": ["loud humor", "celebrity endorsement"],
  "notes": "Q4 focus: gift-shoppers + retention"
}

Strategist tools auto-include this context.

get_brand_taxonomy / set_brand_taxonomy_value / delete_brand_taxonomy_value / set_brand_entity / delete_brand_entity

Customize the standard taxonomy for one brand without breaking cross-brand reporting.

set_brand_taxonomy_value: {
  "brand_name": "Acme",
  "dimension": "talent",
  "value": "Stephen Lavender / Founder",
  "aliases": ["Stephen", "founder"],
  "description": "Use when Stephen appears or is referenced"
}

set_brand_entity: {
  "brand_name": "Acme",
  "entity_type": "product",
  "name": "Creative Tagger",
  "aliases": ["CT", "tagger"]
}

delete_brand_taxonomy_value: {
  "brand_name": "Acme",
  "dimension": "talent",
  "value": "Old Founder Label"
}

delete_brand_entity: {
  "brand_name": "Acme",
  "entity_type": "product",
  "name": "Retired Product"
}

get_naming_variables / list_naming_templates / save_naming_template

Manage saved naming templates from your agent. Templates support standard taxonomy fields plus brand-custom variables like founder, product, offer, customer_segment, icp, and campaign_label. Saved templates auto-apply to future analyze_creative results.

save_naming_template: {
  "name": "default",
  "template": "{brand}_{founder}_{customer_segment}_{hook_type}_{cta}_{ratio}_{version}"
}

Use preview_naming_template to test a template before saving, and delete_naming_template to remove one.

get_meta_status / sync_meta_performance

Check or trigger read-only Meta performance memory. No campaign creation, no budget edits. Creative Tagger must have an approved native Meta OAuth connection before customer accounts can sync Meta performance. Pass attribution_windows when the buyer uses a non-default Meta lookback window and Creative Tagger should match Ads Manager exactly.

{
  "brand_name": "Acme",
  "date_preset": "last_30d",
  "attribution_windows": ["7d_click", "1d_view"]
}

get_creative_strategy_report

Pull the same strategy matrix shown in Creative Tagger Reports. Defaults to visual formats by messaging angles, with states for next tests, live learning, winners, losers, fatigue, and gaps. Returns the decision queue and a bounded matrix slice for agent strategy work. Detailed responses also include an agent_context payload that can be handed directly to an LLM. Supports creative-diagnostics metrics such as CTR, thumbstop, hook, hold, video milestone rates, CPA, CVR, ROAS, revenue, spend, and funnel score. For audience-mode reads, switch the axes to demographic dimensions such as demographic_age and demographic_gender, or use the demographic-read or audience-signals templates. Other built-in templates include creative-winners, fatigue-watch, coverage-gaps, hook-performance, and persona-read. Creative axes follow taxonomy v2: visual_format (execution style), asset_type (production class), and media_type (auto-detected format) are three separate dimensions, with ad_type kept as a deprecated alias for visual_format. Demographics are account-level only, with no per-ad key: pairing a creative tag axis with a demographic axis is structurally not_applicable and returns an explicit cross_contract instead of a populated grid. Audience-mode matrices need BOTH axes to be demographic instead — e.g. demographic_age by demographic_gender (the demographic-read template), or demographic_segment by demographic_signal (the audience-signals template). Add fatigue_minimum_calendar_days when fatigue should only count after a long enough live window, not just after a few close-together synced points. For fatigue-aware reads, pass the same embedded watch controls the app/API support: watch_group_by, watch_metric, watch_signal_focus, watch_trajectory_focus, watch_coverage_focus, watch_minimum_points, watch_minimum_calendar_days, watch_maximum_gap_days, and watch_limit. The decision-queue limit is clamped to 1–25, while watch_limit is clamped to 1–10, before the API request. Responses default to response_format: "concise" with at most 24 matrix cells to keep the result bounded. Set response_format: "detailed" explicitly for the richer report fields, including agent_context. Both formats respect max_cells; raise it (up to 200) when a larger matrix slice is needed.

{
  "brand_name": "Acme",
  "report_template": "next-tests",
  "rows": "visual_format",
  "columns": "messaging_angle",
  "metrics": "spend,ctr,thumbstop_rate,hook_rate,hold_rate,cpa",
  "response_format": "concise",
  "max_cells": 24
}

{
  "brand_name": "Acme",
  "report_template": "demographic-read",
  "rows": "demographic_age",
  "columns": "demographic_gender",
  "metrics": "spend,roas,ctr,cpa,conversions,revenue",
  "roas_target": 2.5,
  "fatigue_minimum_calendar_days": 7,
  "watch_group_by": "hook_type",
  "watch_metric": "cpa",
  "watch_signal_focus": "fatigued",
  "watch_trajectory_focus": "worsening",
  "watch_coverage_focus": "windowed_history",
  "watch_minimum_points": 2,
  "watch_minimum_calendar_days": 7,
  "watch_maximum_gap_days": 7,
  "watch_limit": 5,
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}

{
  "brand_name": "Acme",
  "report_template": "audience-signals",
  "rows": "demographic_signal",
  "columns": "demographic_segment",
  "metrics": "spend,roas,ctr,cpa,conversions,revenue",
  "date_preset": "last_30_days"
}

{
  "brand_name": "Acme",
  "report_template": "hook-performance",
  "rows": "hook",
  "columns": "ad_type",
  "metrics": "spend,hook_rate,hold_rate,roas,ctr,cpa",
  "fatigue_minimum_calendar_days": 7,
  "date_preset": "last_30_days"
}

get_brain_learnings

Read the auto-written Brand Brain learnings generated from performance memory, strategy cells, taxonomy winners/watchouts, and audience signals. Returns a hero learning, concise stories, and an agent_context payload for the next brief or strategist prompt. Use kinds when an agent only wants a focused slice such as conclusion, working,audience, or watch. Add conclusion_statuses to narrow conclusion stories to winner, fatigued, or loser outcomes only, and conclusion_recency_days to keep only the most recent conclusion window. Use watch_group_by, watch_metric, watch_signal_focus, watch_trajectory_focus, watch_coverage_focus, watch_minimum_points, watch_minimum_calendar_days, watch_sources, and fatigue_decay_threshold when the watchouts should be written from a different fatigue lens such as fatigued-only CPA by ad type, weak taxonomy patterns only, CTR by hook, or stable ROAS by demographic_segment. When kinds includes audience, audience_signal_focus accepts the canonical values all, higher_observed_efficiency, or lower_observed_efficiency. The same vocabulary applies to get, save, and export operations. Across all three operations, story limit is clamped to 1–12 and audience_limit is clamped to 1–10 before the API request.

{
  "brand_name": "Acme",
  "date_preset": "last_30_days",
  "minimum_spend": 500,
  "learning_spend": 1500,
  "kinds": "conclusion,watch,audience",
  "audience_signal_focus": "higher_observed_efficiency",
  "conclusion_statuses": "winner,fatigued",
  "conclusion_recency_days": 21,
  "watch_group_by": "ad_type",
  "watch_metric": "cpa",
  "watch_signal_focus": "fatigued",
  "watch_trajectory_focus": "worsening",
  "watch_coverage_focus": "windowed_history",
  "watch_minimum_points": 3,
  "watch_minimum_calendar_days": 7,
  "watch_sources": "timeseries,patterns",
  "fatigue_decay_threshold": 0.25,
  "limit": 6
}

save_brain_learnings

Persist the current auto-written Brand Brain learnings into saved Brain notes for a brand, using the same filtering controls as get_brain_learnings. Use this after reviewing a conclusion/working/watch/audience/gap slice when the user wants the best current learnings saved back into reusable strategist context.

{
  "brand_name": "Acme",
  "date_preset": "last_30_days",
  "minimum_spend": 500,
  "learning_spend": 1500,
  "kinds": "conclusion,watch,audience",
  "audience_signal_focus": "lower_observed_efficiency",
  "conclusion_statuses": "winner,fatigued",
  "conclusion_recency_days": 21,
  "watch_group_by": "ad_type",
  "watch_metric": "cpa",
  "watch_signal_focus": "fatigued",
  "watch_trajectory_focus": "worsening",
  "watch_coverage_focus": "windowed_history",
  "watch_minimum_points": 3,
  "watch_minimum_calendar_days": 7,
  "watch_sources": "timeseries,patterns",
  "include_gaps_in_notes": false,
  "limit": 6
}

export_brain_learnings_context

Export the bounded agent_context from get_brain_learnings, including its filtered learning stories and follow-up Strategy/time-series queries. It uses the same controls and canonical audience_signal_focus values as the get and save tools.

{
  "brand_name": "Acme",
  "kinds": "audience",
  "audience_signal_focus": "higher_observed_efficiency",
  "limit": 6
}

get_performance_timeseries

Read saved performance curves for fatigue checks without opening the dashboard. Returns dated points plus a fatigue signal for each grouped series, using the same decay threshold as Creative Tagger's strategy matrix. Group by creative, campaign, landing page, analysis_id, or audience slices like demographic_age, demographic_gender, demographic_segment, and demographic_signal, and inspect metrics like ROAS, CPA, CTR, CPM, thumbstop, completion rate, or funnel score. Use signal_focus when an agent only wants the current fatigue watchlist or only stable controls, and trajectory_focus when the agent wants only worsening, improving, flat, or insufficient-data series. Use coverage_focus to isolate call-ready, gappy, short-window, or windowed-history curves. Add minimum_calendar_days when fatigue should only count after a trend has been live long enough, not just after a few close-together points. Both this tool and its context export clamp limit to 1–10 grouped series locally.

{
  "brand_name": "Acme",
  "date_preset": "last_30d",
  "group_by": "ad_name",
  "metric": "roas",
  "signal_focus": "fatigued",
  "trajectory_focus": "worsening",
  "coverage_focus": "call_ready",
  "minimum_spend": 500,
  "minimum_points": 3,
  "minimum_calendar_days": 7,
  "fatigue_decay_threshold": 0.18,
  "limit": 5
}

Use date_preset for a standard lookback window, or pass explicit start_date / end_date to override it.

export_performance_timeseries_context

Return the reusable agent_context payload from performance time series. Use this when another agent needs the fatigue decision queue, summary text, action mix, top groups, and prompt-ready export without carrying the full chart payload. It accepts the same inputs as get_performance_timeseries.

{
  "brand_name": "Acme",
  "date_preset": "last_30d",
  "group_by": "ad_name",
  "metric": "roas",
  "signal_focus": "fatigued",
  "trajectory_focus": "worsening",
  "coverage_focus": "call_ready",
  "minimum_spend": 500,
  "minimum_points": 3,
  "minimum_calendar_days": 7,
  "fatigue_decay_threshold": 0.18,
  "limit": 5
}

Internal migration/backfill tools are hidden from the default published MCP surface. They require CREATIVE_TAGGER_INTERNAL_BACKFILL_TOOLS=1 and should not be used in customer flows or to avoid Meta approval.

get_meta_performance_summary

Read saved Meta performance memory without triggering a sync.

{ "brand_name": "Acme" }

Returns account totals plus performance by standard taxonomy and brand-custom taxonomy. Each aggregate can include funnel_score and a funnel explanation object for capture -> hold -> bring-to-site -> convert diagnosis.

get_taxonomy_performance

Find historical tag associations, under-observed tags, and standard taxonomy values that have not been tested. Rows include ROAS, CTR, thumbstop, and funnel scores when performance memory exists. These are observational comparisons; validate a promising tag with a one-variable controlled test.

{ "brand_name": "Acme", "dimension": "hook_type", "spend_threshold": 500 }

get_prebuilt_reports

Return ready-made Motion-style reports: best hooks, landing pages, messaging angles, audiences, offers, CTAs, visual formats, and brand-custom values. Add start_date / end_date when the report should only cover a specific synced window. limit is clamped to 1–50 rows per report before the API request.

{ "brand_name": "Acme", "report_id": "best_hooks", "limit": 8 }
{ "brand_name": "Acme", "report_id": "best_angles", "start_date": "2026-05-01", "end_date": "2026-05-31", "limit": 8 }

create_custom_report

Build a custom report from selected standard or brand taxonomy dimensions and rank the actual matched dimension combinations by ROAS, funnel score, spend, CTR, or CPA. Use this for Motion-style views like best hook x landing page x offer, founder x hook, audience x offer, or brand segment x product. Add start_date and end_date when the report should isolate a specific test window instead of the full synced history. limit is clamped to 1–50 rows before the API request.

attribution accepts blended, 7d_click, 1d_view, or incremental. Omitting it and passing blended return the byte-identical legacy response. The selected basis recomputes only conversion-derived metrics (conversions, revenue, CPA, ROAS, and CVR); delivery, rate, and video metrics stay unchanged. Incremental results are labelled modelled, and an unmeasured conversion value is never turned into zero.

{
  "brand_name": "Acme",
  "dimensions": ["hook_type", "landing_page", "offer_type"],
  "layer": "all",
  "metric": "roas",
  "attribution": "7d_click",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}

Rows can include parts and values, so the agent can explain a winning combination instead of treating each tag independently.

Saved custom reports

Save reusable report definitions, list them for a brand, rerun them by id, or delete them when they are no longer needed. Saved reports can also persist a custom start_date / end_date window for a specific launch or test period, plus dashboard-style preset state such as view_type, date_range, group_by, metrics, filters, sort, and saved_metric_preset. Current chart view types are table, bar, line, and pie. save_custom_report clamps limit to 1–50 rows before the API request. The API accepts attribution on a save request but does not persist it; run_saved_custom_report always replays blended attribution.

{
  "brand_name": "Acme",
  "name": "Hook + LP + Offer",
  "dimensions": ["hook_type", "landing_page", "offer_type"],
  "view_type": "table",
  "date_range": "custom",
  "group_by": "dimension",
  "metrics": ["spend", "roas", "cpa", "ctr"],
  "filters": [{"field": "status", "value": "winner"}],
  "sort": "desc",
  "saved_metric_preset": "delivery",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}
{ "brand_name": "Acme" }
{ "report_id": 7 }

Tools: save_custom_report, list_custom_reports, run_saved_custom_report, delete_custom_report.

get_creative_leaderboard

One ranked list answering "which creatives should I scale or kill." One row per creative for the window (default last_14_days), ranked by rank_by (roas | cpa | spend | ctr | thumbstop, default roas), each with thumbnail/media, spend, spend_share, measurement states, days_running, and a first/second-half trend_direction. A creative below min_spend (default 500, the shared materiality floor) is flagged below_min_spend, excluded from the ranks, and never crowned a winner on thin spend — but still returned and counted. direction (winners | losers | all) slices the ranked half. When the workspace's performance evidence is not decision-safe (stale sync, no Meta connection), rankings_withheld is true and every row drops to observation-only with no rank. launched_after / launched_before (YYYY-MM-DD) scope the ranked population to creatives first synced in that window; limit is clamped to 1–50.

{ "brand_name": "Acme", "window": "last_14_days", "rank_by": "roas", "direction": "winners", "min_spend": 500, "limit": 20 }

get_batch_readout

Grades a launch cohort against the rest of the account. Given a launch window (launched_after / launched_before, YYYY-MM-DD — at least one required), every creative first synced in that window gets a three-way verdict — promising, underperforming, or insufficient_evidence — against a same-window baseline built from every other creative (the baseline excludes the batch, so a new cohort is judged like-for-like, never against its own numbers). verdict_counts totals the three buckets. insufficient_evidence always carries a verdict_reason: most often below_min_spend (expected for roughly half of most batches — that honesty is the point), or metric_not_applicable when the creative's objective/format does not track rank_by (e.g. roas on a leads creative), in which case it is also excluded from the baseline. rank_by is roas | cpa | ctr | thumbstop. Verdicts are withheld when evidence is not decision-safe; limit is clamped to 1–50.

{ "brand_name": "Acme", "launched_after": "2026-06-01", "launched_before": "2026-06-14", "window": "last_30_days", "rank_by": "roas" }

compare_periods

Period-over-period: "is it the ads, the auction, or the site?" Compares period_a (baseline) to period_b (the "after" window); each period is either a preset (this_week, last_week, last_7_days, last_14_days, last_30_days, last_90_days, this_month, last_month) or an explicit period_X_start / period_X_end (YYYY-MM-DD) pair — never both, and the two windows must not overlap. Returns account-level deltas (spend, revenue, ROAS, CPA, CPM, CTR, thumbstop, click-to-purchase rate, AOV) with measurement states honored, plus a multiplicative funnel decomposition whose dominant_factor names why a ROAS/CPA change happened — auction (CPM), creative_engagement (CTR), landing_conversion (CVR), order_value (AOV), or mixed. When revenue reported a measured $0 in a period, the decomposition falls back to CPA and returns a non-null revenue_caution — trust it when present: the revenue collapse itself is the likely explanation, not the delivery reading. Optional group_by (creative or a taxonomy dimension) adds per-value deltas and biggest_movers; limit is clamped to 1–25.

{
  "brand_name": "Acme",
  "period_a_preset": "last_week",
  "period_b_preset": "this_week",
  "metric": "roas",
  "group_by": "hook_type"
}

predict_creative

Despite the legacy tool name, this is not a forecast. It compares a saved analysis or draft attributes with the brand's historical tag-level performance and returns an explicit observational association score and controlled-test hypotheses—never a forecast, lift estimate, or causal recommendation. Turn a promising association into a falsifiable, one-variable controlled test with a predeclared primary metric, minimum data, guardrails, and ship/stop criteria. Since 0.2.3 the package sends the required predict_observational.v2 request handshake and rejects legacy or mixed response shapes instead of decorating them. A contract mismatch returns no prediction evidence.

{
  "brand_name": "Acme",
  "attributes": { "hook_type": "Question", "cta": "Shop Now" },
  "objective_metric": "cpa",
  "goal_direction": "lower_better"
}

get_demographics_performance

Read age x gender delivery with account-relative higher and lower observed- return-per-spend bands. These bands are descriptive associations, not audience outcome or action verdicts. Use date_preset for a standard audience window, or start_date / end_date to isolate a specific audience window.

{
  "brand_name": "Acme",
  "date_preset": "last_30_days",
  "start_date": "2026-05-01",
  "end_date": "2026-05-31"
}

export_demographics_context

Return an agent-ready audience context payload from the saved demographics read. Use this when another agent needs higher and lower observed-efficiency bands, raw totals, per-segment account-wide tag reads and trend views, and a prompt-ready descriptive summary without the full wrapper. Demographics are account-level only, with no per-ad key — every follow-up query stays a separate demographic-only or tag-only read, never a joined tag x demographic cross. Outcome direction stays withheld until an objective metric and direction are predeclared. limit is clamped to 1–100 segments per observed-efficiency band.

{
  "brand_name": "Acme",
  "date_preset": "last_30_days",
  "limit": 3
}

generate_brand_taxonomy

Generate brand-specific messaging themes and intended audiences from the analyzed creative library, then optionally save them to Brand Taxonomy Studio.

{ "brand_name": "Acme", "persist": true }

scan_competitor

Classify a competitor's Meta Ad Library ads and get strategy breakdown. limit is clamped to 1–50 ads before the API request.

{ "brand_name": "Acme", "page_name": "Hims & Hers", "limit": 25 }

Internal competitor-row backfill is also hidden from the default published MCP surface. Customer-facing competitor intelligence should use scan_competitor after native Meta Ad Library access is approved.

get_competitor_scan_history

Read the saved Market scans/imports for a workspace without re-running Meta Ad Library access. Useful when the agent needs the latest saved competitor hooks, styles, or scan metadata before drafting briefs. limit is clamped to 1–50 saved scans before the API request.

{ "brand_name": "Acme", "limit": 6 }

get_competitor_scan_detail

Read one saved competitor scan/import in full, including the stored ads, per-ad analyses, original query, and aggregate strategy breakdown. Use the scan_id returned by get_competitor_scan_history to reopen a specific past market read for grounded follow-up briefing without re-running Meta Ad Library access.

{ "scan_id": 42 }

generate_naming

Build naming strings from already-classified attributes (rarely needed — analyze_creative already includes naming).

Prompts

Beyond the tools above, this server exposes 10 MCP prompts (prompts/list, prompts/get) — turnkey report recipes. Each one tells the calling agent exactly which tools to call, in what order and with what arguments, and how to write up the result: a shared measurement-states vocabulary (measured / not_applicable / not_reported — never a guessed number), spend floors before calling winners or losers, explicit insufficient-evidence verdicts, and a verdict-first, receipts-after output format. Any MCP client with prompt support can run these directly; arguments arrive as strings and are validated the same way tool arguments are — invalid enum values, malformed dates, and reversed date ranges (start after end) all raise a protocol-level INVALID_PARAMS error instead of rendering a broken recipe. Default date windows are UTC-anchored (datetime.now(timezone.utc)); date_preset never accepts custom on a prompt that has no start_date/end_date argument of its own, since an unpaired custom window is unsafe across these tools (some silently read all-time history, others reject it outright).

weekly_creative_report

The Monday artifact: freshness-stamped totals, tag-level winners/losers, top-spender fatigue watch, and a decision queue. brand_name (required), date_preset (last_7_days | last_30_days, default last_7_days), target_roas, target_cpa, spend_threshold (default 500).

fatigue_check

Ranked fatigue watchlist for the top spenders before it shows up in ROAS. brand_name (required), top_n (1-10, default 5), metric (roas | cpa | ctr | thumbstop_rate, default roas), date_preset (last_30d | last_90d, default last_30d).

scale_kill_hold

Morning triage: every material creative bucketed into scale/kill/hold/insufficient-evidence against a declared target. brand_name (required), objective_metric (roas | cpa, required), target_value (required), minimum_spend (default 500), date_preset (all_time | last_7_days | last_30_days | last_90_days, default last_30_days).

what_to_make_next_brief

Turns performance and coverage gaps into next sprint's production brief. brand_name (required), production_slots (default 5), formats_available (optional), date_preset (all_time | last_7_days | last_30_days | last_90_days, default last_30_days).

hook_report

Which hooks earn the view AND the purchase, which get skipped, and which are wearing out. brand_name (required), date_preset (all_time | last_7_days | last_30_days | last_90_days, default last_30_days), spend_threshold (default 500).

batch_readout

Grades a creative batch against the account baseline, with an explicit too-early-to-judge bucket. brand_name (required), batch_start_date (required, YYYY-MM-DD), batch_end_date (default today), baseline_preset (default last_90_days).

monday_money_check

The founder's one-glance verdict: above/below breakeven, better/worse than last week (Meta- attributed only — blended MER is reported not_applicable). brand_name (required), breakeven_roas (required unless target_cpa is given), target_cpa (optional), date_preset (last_7_days | last_30_days, default last_7_days).

competitive_whitespace

Diffs a competitor's live ad strategy against your own library on the same taxonomy. brand_name (required), competitor (optional page name — omit to reuse the latest saved scan), country (default US), run_fresh_scan (default false), date_preset (all_time | last_7_days | last_30_days | last_90_days, default last_90_days).

audience_read

Who your spend is reaching vs. who is efficiently converting, broken by age and gender, reported alongside (never crossed with) messaging-angle and hook performance, as observed associations with the controlled tests that would confirm them. brand_name (required), objective_metric (roas | cpa | ctr, required), goal_direction (maximize | minimize, required, must agree with objective_metric), date_preset (all_time | last_7_days | last_30_days | last_90_days, default last_30_days).

client_review_pack

The monthly business-review skeleton: totals, winner pattern, testing slide, audience read, competitor context, and next month's test proposal. brand_name (required), period_start/period_end (required, YYYY-MM-DD), client_cpa_target (optional), include_competitors (default true).

Architecture

Your AI agent  ←—stdio—→  creative-tagger-mcp  ←—HTTPS—→  api.creativetagger.ai
                                                              │
                                                              ├── Gemini 3.5 Flash (default classifier)
                                                              ├── Claude Sonnet 5 (configured fallback)
                                                              ├── SQLite (library + brand memory)
                                                              └── Meta Ad Library

You bring the agent. We provide the taxonomy, the memory, and the strategist.

License

MIT