AI Knowledge Hub
Menu

Tools & MCP / Ads

Meta Ads MCP Connector

Launchable account-scoped Meta Marketing API MCP server for bounded read-only insights with provider-verified identity and normalized diagnostics.

Access

Read only · Meta Ads

Setup requiredAPI or MCP integrationRequirements & limits

Inputs

The released example shows these fields. Check the guide for which are required.

  • ad_account_id
  • level
  • start_date
  • end_date
  • fields
  • breakdowns
  • page_size
  • max_rows
  • timeout_ms

Outputs

The released example shows these fields. Check the guide for which are required.

  • schema_version
  • ad_account_id
  • business_id
  • level
  • date_range
  • fields
  • breakdowns
  • rows
  • pagination
  • attribution
  • source

Before you begin

  • Node.js 22 or newer.
  • META_ADS_CREDENTIAL and META_ADS_POLICY runtime bindings.
  • A Meta app and token with access to the configured business and sandbox or live ad account.

Try this first

Review the setup requirements, access boundaries and release guide before connected use.

Limits for this step
  • The connector exposes no campaign, budget, creative, audience, or account mutation operation.
  • Reports are limited to the packaged field and breakdown allowlists and the runtime owner's policy budgets.
  • Provider promotion requires a current clean-client smoke observation against an approved sandbox ad account.
  • Insights GET requests only; business, account, fields, breakdowns, dates, pagination, timeout, and response-size limits are enforced before results are returned.
Review setup requirements

Summary sources · Catalogue metadata, tool.yaml, TOOL.md, examples/input.json, examples/output.json · v0.2.0 · Release package

View capabilities and accessHide capabilities and accessv0.2.0

What it can do

  • Read bounded account, campaign, ad set, and ad-level Insights reports for explicitly allowed ad accounts.
  • Preserve provider reporting dates, account timezone, currency, and account attribution settings.
  • Live-verify the Meta application, token principal, permissions, expiry, business, and ad-account relationship.

Access limits

Insights GET requests only; business, account, fields, breakdowns, dates, pagination, timeout, and response-size limits are enforced before results are returned.

Trust boundary · remote-mcp-server

Credentials and setup

  • Meta access token plus application credentials with ads_read and business_management permissions

Install tool files

These commands install package files and generate runtime configuration where supported. Confirm discovery in your agent app, then check configuration, authentication and a first useful operation.

Install (Codex)

./bin/skills-hub install --module tools --entry ads/[email protected] --runtime codex

Install (Claude)

./bin/skills-hub install --module tools --entry ads/[email protected] --runtime claude

Install (Generic)

./bin/skills-hub install --module tools --entry ads/[email protected] --runtime generic --target ./my-agent/tools-mcp

How You Can Use This

Setup required

Resource form: API or MCP integration

Configuration, credentials or runtime bindings are required. Check the prerequisites and limits for your intended environment.

First run: Bind META_ADS_CREDENTIAL and META_ADS_POLICY, then register .mcp.json with Codex, Claude, or a generic MCP client.

Setup required

  • Node.js 22 or newer.
  • META_ADS_CREDENTIAL and META_ADS_POLICY runtime bindings.
  • A Meta app and token with access to the configured business and sandbox or live ad account.

Current limits

  • The connector exposes no campaign, budget, creative, audience, or account mutation operation.
  • Reports are limited to the packaged field and breakdown allowlists and the runtime owner's policy budgets.
  • Provider promotion requires a current clean-client smoke observation against an approved sandbox ad account.
What installation and verification mean
File installation
Places package files and generated configuration in the selected directories.
Native discovery
Your agent app finds and accepts the instructions, tools or plugin registrations.
Mock execution
Exercises sample fixtures. Connected data and provider effects need a separate check.
Connected operation
Requires current configuration, provider authentication, scoped permissions and a successful operation in your intended environment.

Declared compatibility

Maintainer-reviewed information for version 0.2.0 · Reviewed 2026-10-31. This is not a live provider check.

  • Packaged API target: Meta Marketing / Graph API v24.0
  • Runtime: Node.js 22 or newer
  • Uses Node's built-in HTTP functionality; no Meta SDK is packaged.

Limits

  • This release requires graph_api_version v24.0; other versions are rejected.
  • Read-only Insights reporting requires app credentials, a token with ads_read and business_management permissions, and allowed business and ad-account IDs.
  • Reporting fields, breakdowns and request budgets are restricted by the package and configured policy.

Reviewed Meta Ads release implementation

Classification: declared

Technical details and release files

Review and lifecycle

Review maturity: Experimental

Security review declaration: Not declared

Lifecycle: Active

These release declarations are separate from evidence that a workflow operates in your environment.

Runtime & Dependencies

ID: ads/meta-ads-mcp-connector

Tags: meta-ads, mcp, paid-social, read-only

Runtimes: codex, claude, generic

Dependencies & Setup

MCP servers: Not documented

APIs: Meta Marketing API

Local tools: Not documented