Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Motion MCP server

Vendor MCP
Open markdown

The Motion MCP connector routes your AI agent's tool calls to Motion's own MCP server through Scalekit. Each user signs in to Motion once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 15 tools.

Tools
15
What they doRead · write · destructive
14 · 1 · 014 read1 write0 destructive
Users sign in with
OAuth app
Scalekit's or your own

What you can do

  • Analyze ad creatives: pull performance insights, AI summaries, and video transcripts for your own ad creatives
  • Break down results: view ad performance by age and gender and open saved reports
  • Research competitor brands: search brands, list tracked competitors, and browse their creatives by date, format, or platform
  • Get brand context: retrieve brand positioning, voice, messaging angles, and customer voice analysis

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  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. Create the Motion MCP connection

    In AgentKit > Connections, create a Motion MCP connection. The name you give it is the connection_name your code passes. See Configure connections.

    Scalekit credentials are available for Motion MCP server, so you don't need to register an OAuth app.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'motionmcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Motion MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'motionmcp_get_auth_context',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • motionmcp_get_ad_creative_mapBulk export of every Meta ad with spend in a date range, mapped to its Motion creative asset.Read-only

    Get Ad Creative Map

    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.

    Inputs

    organizationIdstringrequired
    The organization ID from get_auth_context
    workspaceIdstringrequired
    The workspace ID from get_auth_context
    datePresetstring
    Predefined date range. Omit if using startDate/endDate.one of TODAYYESTERDAYTHIS_MONTHLAST_MONTHLAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_90_DAYSCUSTOM
    endDatestring
    Custom end date (YYYY-MM-DD). Requires datePreset=CUSTOM.
    limitinteger
    Rows per page, up to 1000.default 1000
    offsetinteger
    Zero-based row offset. Use multiples of limit; pages can be requested in parallel.default 0
    startDatestring
    Custom start date (YYYY-MM-DD). Requires datePreset=CUSTOM.
  • motionmcp_get_auth_contextRetrieve the authenticated user's organizations and workspaces.Read-only

    Get Auth Context

    Retrieve the authenticated user's organizations and workspaces. Returns the workspaceId required by all other Motion tools.

    Inputs

    This tool takes no inputs.

  • motionmcp_get_brand_by_domainResolve a brandId from a website domain or URL.Read-only

    Get Brand By Domain

    Resolve a brandId from a website domain or URL. Returns null if no brand is found for the given domain.

    Inputs

    brandUrlstringrequired
    Brand URL or domain, for example `https://example.com`
    workspaceIdstringrequired
    The workspace ID for authorization
  • motionmcp_get_creative_insightsRetrieve creative performance insights for your own ads in a workspace.Read-only

    Get Creative Insights

    Retrieve creative performance insights for your own ads in a workspace. Either datePreset or both startDate and endDate must be provided.

    Inputs

    insightTypestringrequired
    Primary metric to sort/rank creatives byone of SPENDSCALINGHOOKROASPURCHASESPURCHASE_VALUECTR_ALLCPACPC
    organizationIdstringrequired
    The organization ID from get_auth_context
    workspaceIdstringrequired
    The workspace ID from get_auth_context
    chartKPIsarray
    Optional KPI fields to include in chart KPI metrics.
    clickAttributionWindowstring
    Override the workspace Meta click attribution window, e.g. "1d_click" or "7d_click".one of 1d_click7d_click28d_clickskan_click
    creativeAssetIdsarray
    Optional creative asset IDs to narrow results.
    cursorstring
    Opaque cursor from the previous response. Reuse all other query parameters unchanged.
    datePresetstring
    Predefined date range. Omit if using startDate/endDate.one of TODAYYESTERDAYTHIS_MONTHLAST_MONTHLAST_7_DAYSLAST_14_DAYSLAST_30_DAYSLAST_90_DAYSCUSTOM
    endDatestring
    Custom end date (YYYY-MM-DD). Requires datePreset=CUSTOM.
    filtersarray
    Nested filter groups to narrow which creatives are returned. Outer array = AND (all groups must pass); inner array = OR (any filter in a group can match). For text fields (campaignName, adsetName, adName): use "value" (singular) for case-insensitive substring match, or "values" (array) for exact match. For metric fields: set "metric": true and use "value" for thresholds or "values" for ranges. Example: [[{"field":"spend","type":"GREATER_THAN","value":"100","metric":true}],[{"field":"campaignName","type":"includes","value":"Prospecting"}]] returns creatives where spend > 100 AND campaign name contains "Prospecting".
    groupBystring
    How to group ranked rows. Options: 'creative' (default — one row per creative asset), 'adId' (one row per ad — for ad-level optimization, comparing same creative across ad sets, deciding which ad to pause/scale), 'name' (by ad name), 'copy' (by ad body text — 'which copy performs best?'), 'headline' (by headline text), 'landingPage' (by destination URL — 'which landing page converts best?').one of creativeadIdnamecopyheadlinelandingPage
    includeCreativeUrlsboolean
    Include public creative URLs for the interactive gallery. Defaults true; set false only for text-only output.default true
    includeEntityCategoryValuesboolean
    Include the full taxonomy catalog (all possible values) per glossary category. Default false — only the values applied to each creative are returned. Set true when you need to see all available tags for coverage gap analysis.default false
    includeGlossaryboolean
    Include creative taxonomy/glossary tags per creative. Default false to minimize payload. Set true for creative pattern analysis.default false
    includeNorthbeamboolean
    Include Northbeam attribution metrics when the workspace has a Northbeam connection. Only supported with groupBy "adId" or "name".default false
    insightGroupsarray
    Metric groups per creative. Defaults: spendState, performance, motion, click.
    limitinteger
    Requested rows per page. The tool caps each page at 25 rows; use nextCursor to retrieve additional pages.default 25
    startDatestring
    Custom start date (YYYY-MM-DD). Requires datePreset=CUSTOM.
    tableKPIsarray
    Optional KPI fields to include in table KPI metrics.
    viewAttributionWindowstring
    Override the workspace Meta view attribution window, e.g. "1d_view" or "7d_view".one of 1d_view7d_view28d_viewskan_view
    withAggregatedInsightsboolean
    Include account-level aggregated metricsdefault false
  • motionmcp_get_creative_summaryFetch a compact AI-generated summary for a specific creative asset in a workspace.Read-only

    Get Creative Summary

    Fetch a compact AI-generated summary for a specific creative asset in a workspace.

    Inputs

    creativeEntityIdstringrequired
    Mongo ObjectId of the creative entity
    creativeFormatstringrequired
    Creative format from the source tool. Pass through the source value; `unknown` may fail if no compatible summary prompt exists.one of videoimageunknown
    creativeOriginstringrequired
    Source/origin of the creativeone of metaCreativeAssettiktokCreativeAssetyoutubeCreativeAssetlinkedinCreativeAssetmetaAdLibraryCreativetiktokAdLibraryCreativeinstagramAdLibraryCreativetiktokOrganicAdLibraryCreative
    organizationIdstringrequired
    The organization ID from get_auth_context
    workspaceIdstringrequired
    The workspace ID from get_auth_context
  • motionmcp_get_creative_transcriptFetch the spoken transcript for a video creative by its entity ID and workspace.Read-only

    Get Creative Transcript

    Fetch the spoken transcript for a video creative by its entity ID and workspace.

    Inputs

    creativeEntityIdstringrequired
    Mongo ObjectId of the creative entity
    creativeOriginstringrequired
    Source/origin of the creativeone of metaCreativeAssettiktokCreativeAssetyoutubeCreativeAssetlinkedinCreativeAssetmetaAdLibraryCreativetiktokAdLibraryCreativeinstagramAdLibraryCreativetiktokOrganicAdLibraryCreative
    workspaceIdstringrequired
    The workspace ID from get_auth_context
    creativeFormatstring
    Creative format (video or image). Transcript data is only available for video creatives; image creatives will return empty transcript data.one of videoimagedefault video
  • motionmcp_get_glossary_valuesReturn the workspace's glossary taxonomy — categories and their allowed tag values.Read-only

    Get Glossary Values

    Return the workspace's glossary taxonomy — categories and their allowed tag values.

    Inputs

    workspaceIdstringrequired
    The workspace ID
    categoryNamesarray
    Optional list of glossary category internal names
    customOnlyboolean
    Return only custom glossary categoriesdefault false
    includeCreativeIdsboolean
    Include creative IDs in value bucketsdefault false
  • motionmcp_get_inspo_brand_contextRetrieve strategic brand context for an Inspo brand, including positioning, voice, tone, messaging angles, and customer voice analysis.Read-only

    Get Inspo Brand Context

    Retrieve strategic brand context for an Inspo brand, including positioning, voice, tone, messaging angles, and customer voice analysis.

    Inputs

    brandIdstringrequired
    The brand ID to get Inspo context for
    workspaceIdstringrequired
    The workspace ID for authorization
All 40 in Project Management