Meta Ads MCP Server - Campaign management via the configured Meta Graph API (default: v25.0).

Management server for Meta Ads. Provides full CRUD operations, performance insights, targeting discovery, bulk operations, and specialized features like entity duplication and delivery estimates. Designed for AI agents to manage Meta Ads campaigns programmatically through the Model Context Protocol with per-session Bearer token authentication.

• Self-host this connector when you want direct control of credentials, infrastructure, and Meta Ads API access.
• Use Cesteral Intelligence when the workflow needs approvals before spend commits, credential brokering, auditability, and cross-platform execution.

Self-host quickstart | Compare OSS vs Cesteral Intelligence | Book a workflow demo

• Per-session Bearer token auth via MetaBearerAuthStrategy (validates tokens against GET /me)
• Streamable HTTP + stdio transports via Hono + @hono/mcp
• OpenTelemetry instrumentation for traces and metrics
• Rate limiting via shared RateLimiter class (200/min default, writes cost 3x)
• Structured logging via Pino
• MCP Resources for entity schemas, examples, insights reference, and targeting reference
• MCP Prompts for campaign setup, insights reporting, troubleshooting, and schema exploration

List Meta Ads entities with optional filtering and cursor-based pagination.

Parameters:

• entityType (string, required): Type of entity to list
• adAccountId (string, required): Ad Account ID (with or without act_ prefix)
• fields (string[], optional): Field names to return
• filtering (array, optional): Filter objects in Meta filtering format
• limit (number, optional): Results per page (1-100, default 25)
• after (string, optional): Cursor for next page

Get a single Meta Ads entity by ID.

Parameters:

• entityType (string, required): Type of entity to retrieve
• entityId (string, required): The entity ID
• fields (string[], optional): Field names to return

Create a new Meta Ads entity.

Parameters:

• entityType (string, required): Type of entity to create
• adAccountId (string, required): Ad Account ID
• data (object, required): Entity fields as key-value pairs

Update an existing Meta Ads entity (POST with PATCH semantics).

Parameters:

• entityType (string, optional): Type of entity to update (informational only, not used in API call)
• entityId (string, required): The entity ID to update
• data (object, required): Fields to update as key-value pairs

Delete a Meta Ads entity.

Parameters:

• entityType (string, required): Type of entity to delete
• entityId (string, required): The entity ID to delete

List ad accounts accessible to the authenticated user.

Parameters:

• fields (string[], optional): Field names to return (defaults to id, name, account_status, currency, timezone_name, amount_spent, balance)
• limit (number, optional): Number of accounts to return (1-100)
• after (string, optional): Pagination cursor from previous response

All Meta reporting tools (meta_get_insights, meta_get_insights_breakdowns, and the meta_download_report tool used in async report flows) return data using the shared bounded report-view contract: mode ("summary" default — headers + counts + 10-row preview, or "rows" for a paginated rows page), columns (project to selected columns), offset (zero-based pagination), and maxRows (page size; default 10 for summary, 50 for rows; hard cap 200). limit and after remain available for cursoring across upstream Meta pages.

Get performance insights for a Meta Ads entity (account, campaign, ad set, or ad).

Parameters:

• entityId (string, required): Entity ID to get insights for
• fields (string[], optional): Metrics/fields to return
• datePreset (string, optional): Date preset (today, yesterday, last_7d, last_30d, etc.)
• timeRange (object, optional): Object with since and until (YYYY-MM-DD)
• timeIncrement (string, optional): Granularity (1 for daily, 7 for weekly, monthly, all_days)
• level (string, optional): Aggregation level (account, campaign, adset, ad)
• limit (number, optional): Upstream Meta page size (1-500). Use maxRows to control the bounded view's returned-row count.
• after (string, optional): Cursor for next upstream page
• mode, columns, offset, maxRows (optional): Bounded report-view params (see note above)

Get performance insights broken down by dimension (age, gender, country, device, etc.).

Parameters:

• entityId (string, required): Entity ID to get insights for
• breakdowns (string[], required): Breakdown dimensions (e.g., ['age', 'gender'])
• fields (string[], optional): Metrics to return
• datePreset (string, optional): Date preset
• timeRange (object, optional): Object with since and until
• timeIncrement (string, optional): Time granularity
• level (string, optional): Aggregation level
• actionAttributionWindows (string[], optional): Attribution windows (e.g., ['1d_click', '7d_click'])
• limit (number, optional): Upstream Meta page size (1-500). Use maxRows for bounded-view row count.
• after (string, optional): Cursor for next upstream page
• mode, columns, offset, maxRows (optional): Bounded report-view params (see note above)

Batch update status for multiple Meta Ads entities.

Parameters:

• entityType (string, optional): Type of entities to update (informational only, not used in API call)
• entityIds (string[], required): Entity IDs to update (max 50)
• status (string, required): ACTIVE, PAUSED, or ARCHIVED

Batch create multiple entities of the same type.

Parameters:

• entityType (string, required): Type of entities to create
• adAccountId (string, required): Ad Account ID
• items (array, required): Array of entity data objects (max 50)

Batch update multiple entities with individual data payloads.

Parameters:

• entityType (string, optional): Type of entities being updated (informational only, not used in API call)
• items (array, required): Array of update items (max 50), each with entityId and data

Search for targeting options (interests, behaviors, demographics) by keyword.

Parameters:

• type (string, required): Search type (adinterest, adinterestsuggestion, adgeolocation, adlocale, etc.)
• query (string, required): Search keyword
• limit (number, optional): Max results (1-100, default 25)

Browse available targeting categories for an ad account.

Parameters:

• adAccountId (string, required): Ad Account ID
• type (string, optional): Filter by targeting type (e.g., interests, behaviors)

Duplicate a campaign, ad set, or ad via POST /{id}/copies.

Parameters:

• entityType (string, required): Type of entity to duplicate (campaign, adSet, ad)
• entityId (string, required): ID of the entity to duplicate
• renameOptions (object, optional): Object with prefix and/or suffix for naming
• statusOption (string, optional): Status for copy (ACTIVE, PAUSED, INHERITED)

Get estimated audience size and delivery estimates for a targeting spec.

Parameters:

• adAccountId (string, required): Ad Account ID
• targetingSpec (object, required): Targeting specification (must include geo_locations or custom_audiences)
• optimizationGoal (string, optional): Optimization goal (e.g., LINK_CLICKS, REACH, CONVERSIONS)

Get preview HTML for an ad in a specific format.

Parameters:

• adId (string, required): Ad ID to preview
• adFormat (string, required): Ad format (e.g., DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD)

Batch adjust ad set bid amounts with percentage or absolute changes.

Parameters:

• adAccountId (string, required): Ad Account ID
• adjustments (array, required): Array of bid adjustments (max 50), each with adSetId, adjustmentType (percentage/absolute), and value

Client-side validation of entity payloads without making API calls.

Parameters:

• entityType (string, required): Type of entity to validate
• mode (string, required): Validation mode (create or update)
• data (object, required): Entity data to validate
• adAccountId (string, optional): Required for create mode
• entityId (string, optional): Required for update mode

Entity Hierarchy: Ad Account > Campaign > Ad Set > Ad (+ Ad Creatives, Custom Audiences)

Phase: Production-Ready

All listed tools are fully implemented using the configured Meta Graph API with Bearer token authentication, insights reporting, and targeting discovery.

# Install dependencies
pnpm install

# Run in development mode
pnpm run dev:http

# Build
pnpm run build

# Start production server
pnpm run start

# Type check
pnpm run typecheck

• META_MCP_PORT: Server port (default: 3005)
• META_MCP_HOST: Server host (default: 127.0.0.1)
• MCP_AUTH_MODE: Authentication mode - meta-bearer (default), jwt, or none
• MCP_AUTH_SECRET_KEY: Required when MCP_AUTH_MODE=jwt
• META_API_BASE_URL: Graph API base URL (default: https://graph.facebook.com/v25.0)
• META_API_VERSION: API version (default: v25.0)
• META_RATE_LIMIT_PER_MINUTE: Rate limit ceiling (default: 200)
• META_ACCESS_TOKEN: Access token for stdio mode
• META_VIDEO_UPLOAD_MAX_BUFFERED_BYTES: Max buffered video upload size in bytes (default: 268435456)

• MetaGraphApiClient - HTTP client for the configured Graph API version with form-encoded POST for writes
• MetaService - CRUD, bulk ops, duplication, delivery estimates, ad previews
• MetaInsightsService - Insights queries with breakdowns, attribution windows, and time series
• MetaTargetingService - Targeting search and category browsing
• MetaBearerAuthStrategy - Bearer token auth via GET /me validation
• MetaAuthAdapter - Token management for per-session API calls
• SessionServiceStore - Per-session service instances keyed by session ID

• Budget values are in cents (e.g., 1000 = $10.00)
• special_ad_categories is required on campaign creation even if empty ([])
• meta_update_entity returns {success: true} — fetch the entity after to confirm changes
• targeting on ad sets replaces entirely on update (no merge semantics)
• ARCHIVED status is permanent and cannot be reversed
• Insights data may lag up to 48 hours for recent activity
• Video uploads use a buffered proxy path and are intentionally capped below Meta's largest native upload limits

Streamable HTTP via Hono + @hono/mcp. Health check at /health.

See root CLAUDE.md for development guidelines, build system details, and monorepo conventions. See the root README for full architecture context.

Self-host: Follow the deployment guide to run this server on your own infrastructure.

Cesteral Intelligence: Request access -- governed execution with credential brokering, approvals, audit, and multi-tenant access.

Book a workflow demo: See it in action with your own ad accounts.

Compare options: OSS connectors vs Cesteral Intelligence

Apache License 2.0 — see LICENSE for details. This package is part of Cesteral's open-source connector layer; managed hosting and higher-level governance features live outside this repository.