Motion MCP Integration for AI Agents

Call this FIRST before any workspace-scoped tool. Returns the authenticated user's organizations and workspaces. Use the returned workspaceId to call all other tools. If the user has exactly one workspace, defaultWorkspaceId is set automatically. If multiple workspaces exist, the user will be prompted to select one. This call records private operational logs and usage telemetry.

Lists competitor brands the workspace is tracking. Input: required `workspaceId` and optional `brandIds` to narrow to a specific competitor set. Returns each competitor with a `brandId` reference suitable for further brand intelligence lookups. This call records private operational logs and usage telemetry.

Returns the workspace's own `brandId` — a reference, not full brand details. Input: required `workspaceId`. The returned `brandId` can then be passed to `get_inspo_brand_context` for positioning, voice, and visual identity, or included in `brandIds` on `get_inspo_creatives` to pull the workspace's own inspo creatives. This call records private operational logs and usage telemetry.

Retrieves a page of creative performance insights (your own ads) for a workspace and displays them in an interactive gallery with thumbnails and playable videos. Input: required `organizationId`, `workspaceId`, and `insightType`, plus optional date range (`datePreset` or `startDate`/`endDate`), metric expansion (`insightGroups`, `tableKPIs`, `includeGlossary`, `includeEntityCategoryValues`, `includeCreativeUrls`, `withAggregatedInsights`, `includeNorthbeam`), attribution overrides (`clickAttributionWindow`, `viewAttributionWindow`), and `groupBy` ('creative' default; pass 'adId' for ad-level rows when the user wants to compare the same creative across ads, ad sets, or campaigns). Responses are paginated. `limit` requests the page size and is capped at 25 rows; when `nextCursor` is non-null, call again with identical query parameters and `cursor=nextCursor` until it is null. The v3 payload returns report metadata under `data.data`, with ranked rows at `data.data.insightsResult.data.insights`. The first response includes `goalMetric` (the workspace's preferred efficiency metric) and `spendThreshold` (minimum spend for statistical significance); `customConversions` lives at `data.data.insightsResult.data.customConversions` and is used to build `tableKPIs` keys for custom conversion analysis. Default response includes public creative URLs and only `defaultKpiMetrics` (spend, cpm, ctr, thumbstop_ratio, video retention, etc.) per ranked insight. Set `includeCreativeUrls` to false only for a text-only response. Set `includeNorthbeam` only with `groupBy: 'adId'` or `groupBy: 'name'`. When `includeGlossary` is enabled, glossary metadata is compacted by hoisting category definitions into `data.data.glossarySchema` and rewriting each ranked insight glossary to an internalName -> string[] map. Every ranked insight includes the full entity hierarchy under `ad` — `adId`, `adName`, `adsetId`, `adsetName`, `campaignId`, `campaignName` — so a single creative asset that runs across multiple ads, ad sets, and campaigns can be compared across contexts. If report generation is still in progress, the tool returns `status: 'waiting'` with `pollAfterMs`; call again with identical params. The request may write private compilation state and enqueue an internal report job over stored Motion data, but it does not start a live Facebook report. This call records private operational logs and usage telemetry.

Returns ad performance broken down by age and gender demographics for a workspace. Resolve workspaceId via get_auth_context first. This is the audience layer — it answers WHO responds to your ads. Always pair with get_creative_insights(SPEND) to interpret demographic signals. Call for: audience/persona/targeting questions, stakeholder reports, adaptation tasks, concept generation, and production planning. A segment with high thumbstop but zero ROAS is a funnel problem, not a creative problem. A segment with low spend but strong efficiency is an underexploited opportunity. The request may start a private Meta async report and update private report caches. This call records private operational logs and usage telemetry.

Bulk export of every Meta ad with spend in a date range, mapped to its Motion creative asset. Use for programmatic or data-pipeline pulls (e.g. 'which ads share the same creative?'), not for performance analysis — use get_creative_insights for that. Each row is { adId, adName, adsetId, campaignId, creativeAssetId, launchDate, spend }. Ads that share a creativeAssetId run the same creative. Rows are sorted by spend descending. Pages hold up to 1000 rows (`limit`, default 1000). Pagination is offset-based: the response includes `pagination.totalCount` and `pagination.nextOffset`; to fetch everything, request offsets 0, limit, 2*limit, ... up to totalCount — these calls are independent and can run in parallel. If a page returns fewer rows than `limit` while `nextOffset` is non-null, also fetch from `nextOffset` so no rows are skipped. Keep the date range and limit identical across pages. If the report is still compiling, the tool returns `status: 'waiting'` with `pollAfterMs`; call again with identical params. Ads without a resolved creative asset and catalog/feed (dynamic product) ads are excluded. The request may write private compilation state and enqueue an internal report job over stored Motion data, but it does not start a live Facebook report. This call records private operational logs and usage telemetry.

Gets a compact AI summary for a specific creative or, when one is absent, creates private generation state and queues AI summarization. Resolve workspaceId via get_auth_context first. Use this after get_creative_insights or get_inspo_creatives when the user explicitly asks for more detail on one specific ad and you need more context than metrics, copy, or transcript alone can provide. Returns the AI-detected ad format, a plain-language summary of what the ad is about, the strongest available hook or headline, and detected CTAs in a compact inline payload. Prefer one creative at a time; small comparison sets are okay, but this is a drill-in tool, not a broad discovery tool. If the summary is still generating, the tool returns waiting and should be polled until complete. This call records private operational logs and usage telemetry.

Gets the spoken transcript for a video creative or, when one is absent, processes the private video through a transcription provider and saves and indexes the result in Motion. Only works for video creatives — set `creativeFormat` to "video". Requires `workspaceId`, `creativeEntityId`, and `creativeOrigin` (both entity fields are available on rows returned by get_creative_insights or get_inspo_creatives). The first 1-3 seconds of the transcript is the hook, the most critical element for creative performance. This call records private operational logs and usage telemetry.

Returns the workspace's glossary taxonomy — categories and their allowed tag values. Resolve workspaceId via get_auth_context first. This is the creative taxonomy layer — when cross-referenced with performance data from get_creative_insights (use includeGlossary: true), it enables pattern-level insights: which categories are scaling, which have the best efficiency by the workspace goalMetric, what combinations appear in winners but not losers, and what hasn't been tried yet (coverage gaps = creative opportunities). Use categoryNames to narrow to specific categories, customOnly to see only user-defined categories, and includeCreativeIds: true to map tagged creatives back to performance data. Also use to validate tag values before filtering — e.g., confirm "UGC" is a valid tag rather than guessing. This call records private operational logs and usage telemetry.

Returns the user's saved reports. Resolve workspaceId via get_auth_context first. Two modes: (1) Omit reportId to list all reports — returns lean metadata (name, type, platform, date range, groupBy, reportUrl). (2) Provide reportId to get the full report configuration — includes reportUrl, filters, attribution selection (standard click/view windows or incrementalityAttribution: true), metrics, comparison settings, and all saved parameters. Use the returned reportUrl when linking to the report; it is null when Motion has no report-detail route for that type. Use the full config to understand what the report tracks, then call get_creative_insights with matching parameters (datePreset, groupBy, filters) to fetch the actual performance data. This call records private operational logs and usage telemetry.

Retrieves rich Inspo brand context for a brand — the strategic foundation layer. Returns brand foundations (positioning, voice, tone, messaging angles), product information, and customer voice analysis for the given `brandId`. When `contextData` is null, inspect `reason` to decide how to proceed: `brand_not_found` (no brand matches the provided brandId) or `not_generated` (no context exists for this brand in either the new or legacy storage). Requires `workspaceId` for authorization. This call records private operational logs and usage telemetry.

Search for brands by name or domain. Input: `query` (the search string) and `workspaceId` for authorization, plus optional `verbose` (default false) to include full per-brand catalog fields. Returns matching brand records each with an `id`, `name`, and optional `domain`, `logo`, `type`, and `industry`. Default response omits heavy catalog fields (`visualFormats`, `topLandingPages`) — pass `verbose: true` or call `get_brand_by_domain` for full detail. Queries of at least three characters also enqueue a private background brand-discovery persistence task to refresh future results. This call records private operational logs and usage telemetry.

Retrieves Inspo creatives for one or more brands and displays them in an interactive gallery with thumbnails and playable videos. Returns an array of brand entries shaped like `{ id, brandDetails, creatives }`, not a brandId-keyed map. Input: `brandIds` (required) plus optional `limit` (default 50, max 1000), `launchDate` filter, `status`, `sort`, and `withGlossary`. Returns creative metadata and ad copy but NO performance metrics — ad libraries do not include spend data, so results represent competitor bets, not measured performance. Set `withGlossary=true` only when you need Motion glossary tags. This call records private operational logs and usage telemetry.

Resolves a brandId from a website domain or URL. Pass the root domain (e.g. "https://example.com") — not a subdomain, deep link, or social media URL. Returns null brandId if no brand is found for the domain. Example: user says "show me ads from example.com" -> call get_brand_by_domain with brandUrl="https://example.com" -> use the returned brandId with get_inspo_brand_context or include it in `brandIds` when calling get_inspo_creatives. If no brand is found, suggest using search_brands to search by name instead. This call records private operational logs and usage telemetry.

Sends one feedback entry about this Motion MCP server to the Motion product team. Scope is limited to capabilities provided by this server — do not use it to submit feedback about other MCP servers, plugins, or unrelated tools. This is a user-initiated write action: only call it when the user has explicitly asked to send feedback, flag an issue, or log a request. Do not call it speculatively on behalf of the user, and do not infer consent from frustration, tone, or surprise alone. When get_creative_insights returns a non-retriable data-availability error such as stored_meta_data_unavailable or meta_datasource_unavailable, first tell the user the creative rows cannot be returned right now and offer to flag the workspace/date range/error to the Motion team; call submit_feedback only after the user agrees. The caller should confirm the category, comment, and intent with the user before submitting, and should send at most one entry per distinct issue per conversation. The submitted feedback plus authenticated user and organization identifiers are recorded in private Motion logs and may be delivered to the Motion product team through Slack.