schema_version: "2.0"
id: ads/meta-ads-mcp-connector
name: Meta Ads MCP Connector
description: Launchable account-scoped Meta Marketing API MCP server for bounded read-only insights with provider-verified identity and normalized diagnostics.
version: 0.2.0
released_at: "2026-09-19T00:00:00Z"
category: tools-mcp/ads
tags: [meta-ads, mcp, paid-social, read-only]
license: MIT
author:
  name: AI Skills Guide Maintainers
  url: https://github.com/ai-knowledge-hub/ai-skills-guide
repository: https://github.com/ai-knowledge-hub/ai-skills-guide
runtimes: [codex, claude, generic]
entrypoints:
  spec: TOOL.md
  readme: README.md
  tests: tests/meta_ads_mcp_server.test.mjs
  scripts_dir: scripts
  examples_dir: examples
dependencies:
  apis: [Meta Marketing API]
operational:
  connected_system: Meta Ads
  capabilities:
    - 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.
  auth_required:
    - Meta access token plus application credentials with ads_read and business_management permissions
  access_level: read-only
  trust_boundary: remote-mcp-server
  approval_boundary: Insights GET requests only; business, account, fields, breakdowns, dates, pagination, timeout, and response-size limits are enforced before results are returned.
usability:
  availability: setup-required
  execution: remote-integration
  requires_setup:
    - 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.
  limitations:
    - 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.
  quickstart: Bind META_ADS_CREDENTIAL and META_ADS_POLICY, then register .mcp.json with Codex, Claude, or a generic MCP client.
execution:
  kind: mcp-server
  command: [node, scripts/meta_ads_mcp_server.mjs]
  healthcheck: [node, scripts/meta_ads_mcp_server.mjs, --healthcheck]
  smoke_test: [node, scripts/meta_ads_mcp_server.mjs, --smoke]
  supported_platforms: [linux, macos]
  supported_runtimes: [node22]
artifact:
  self_contained: true
  dependency_lock: null
  checksums: null
  sbom: null
authentication:
  status: required
  methods: [bearer-token]
  credential_bindings: [META_ADS_CREDENTIAL, META_ADS_POLICY]
  scopes: [ads_read, business_management]
  setup_url: https://developers.facebook.com/apps/
  credential_storage: Access tokens and application credentials remain in explicitly bound runtime environment sources and are never written into the package or readiness profile.
  validation: The packaged driver uses Meta debug_token to verify application binding, principal, permissions, and lifetime, then verifies the selected ad account and owning business with that same token.
  revocation: Invalidate the token in Meta Business Settings, remove the system user or app from the ad account, or rotate the Meta application secret.
verification:
  tests_min_prompts: 5
  deterministic_scripts: true
  security_reviewed: false
  evidence:
    - evidence://tests/meta-ads-mcp/json-rpc-clean-client-launch
    - evidence://tests/meta-ads-mcp/provider-app-principal-scope-expiry
    - evidence://tests/meta-ads-mcp/business-account-isolation
    - evidence://tests/meta-ads-mcp/pagination-rate-limit-timeout-wire-bounds
  last_verified_at: "2026-09-19T00:00:00Z"
deprecated: false