Meta Ads Codex MCP
Provides tools for reading Meta Ads performance data, allowing listing ad accounts, checking active ads, reading ad performance, and summarizing account-level spend.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Meta Ads Codex MCP Which active ads have the highest CPC over the last 7 days?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Meta Ads Codex MCP
A local MCP server that lets Codex answer conversational questions about Meta Ads performance.
Example prompts in Codex:
Use Meta Ads to show how my live ad is performing.
How much have I spent in total?
Which active ads have the highest CPC over the last 7 days?
Summarize my account performance for the last 30 days.This project runs locally. It does not send your Meta Ads token anywhere except Meta's official MCP endpoint at https://mcp.facebook.com/ads.
Codex provides the AI conversation. This package provides the local MCP tools that let Codex safely read Meta Ads data.
Current Status
This first release is read-only. It exposes safe tools for:
listing ad accounts
checking active ads
reading ad performance
reading account-level spend
summarizing account performance
Write actions such as pausing ads, changing budgets, or creating campaigns are intentionally not included yet.
Related MCP server: mcp-meta-marketing
Requirements
Node.js 18+
Codex CLI
A Meta MCP-compatible access token
Meta's official hosted MCP OAuth currently does not support every MCP client. This server supports token-based access by reading a token from an environment variable or local config file.
Quick Start
Install from this repo:
npm install -g .Store a token:
meta-ads-codex-mcp token setOptionally set your default ad account:
meta-ads-codex-mcp account set 2051892919047874Install the MCP server into Codex:
meta-ads-codex-mcp install-codexRestart Codex, then ask:
Use Meta Ads to show how my live ad is performing.Token Sources
The server looks for a token in this order:
META_ADS_MCP_ACCESS_TOKEN~/.meta-ads-codex-mcp.json~/.meta_ads_mcp_token.jsonfrom the local prototype helper
The config file is written with 0600 permissions.
CLI
meta-ads-codex-mcp check
meta-ads-codex-mcp accounts
meta-ads-codex-mcp active-ads --date-preset last_7d
meta-ads-codex-mcp spend --date-preset maximum
meta-ads-codex-mcp performance --ad-id 120247766096870426 --date-preset last_7d
meta-ads-codex-mcp serverCodex Config
install-codex runs:
codex mcp add meta_ads_codex -- meta-ads-codex-mcp serverYou can remove it with:
codex mcp remove meta_ads_codexSecurity
Treat Meta access tokens like passwords.
Do not commit
.env, local config, or token files.This package does not log token values.
Use read-only tokens when possible.
Development
Run the server locally:
node src/cli.js serverRun a direct check:
node src/cli.js checkAvailable Tools
6 toolsmeta_ads_account_summaryB
Read-only. Get account-level performance summary for a date preset.
Inputs: date_preset, ad_account_id, advertiser_request.
meta_ads_active_adsC
Read-only. List active ads and their performance for the default or supplied ad account.
Inputs: limit, date_preset, ad_account_id, advertiser_request.
meta_ads_ad_performanceB
Read-only. Get performance for one ad by ID.
Inputs: ad_id (required), date_preset, ad_account_id, advertiser_request.
meta_ads_list_accountsB
Read-only. List Meta ad accounts available to the authenticated user.
Inputs: advertiser_request.
meta_ads_performance_trendC
Read-only. Ask Meta's insight tool for performance trend analysis.
Inputs: entity_ids, ad_account_id, analysis_level, analysis_metric, +3 more.
meta_ads_total_spendA
Read-only. Get total account spend for the default or supplied ad account.
Inputs: date_preset, ad_account_id, advertiser_request.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Tools are mostly distinct: list_accounts, active_ads, ad_performance, total_spend, account_summary, and performance_trend each target a different aspect. However, some overlap exists between total_spend and account_summary (which likely includes spend), and between active_ads and account_summary (both provide performance data), potentially causing confusion.
All tools share the meta_ads_ prefix and use snake_case, giving a consistent style. However, the pattern is not strictly verb_noun: list_accounts uses a verb, while active_ads, ad_performance, total_spend, account_summary, and performance_trend are noun phrases, mixing adjectives and nouns.
Six tools is a well-scoped number for a read-only Meta Ads reporting server. Each tool covers a specific reporting need without unnecessary bloat, making the set easy to navigate and use.
The set covers core read-only reporting aspects: listing accounts, active ads, single ad performance, total spend, account summary, and trend analysis. Minor gaps exist, such as no listing of inactive ads or detailed campaign/insight breakdowns, but the surface is sufficient for most reporting use cases.
Maintenance
Related MCP Connectors
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Hosted Meta Ads MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Meta Ads and Google Ads MCP server: 250+ tools for Claude, ChatGPT, Cursor and Codex.
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
Related MCP Servers
- AlicenseCqualityCmaintenanceA local Model Context Protocol server that enables interaction with the Meta Marketing API to manage ad accounts, campaigns, and creatives. It provides tools for targeting research, insight reporting, and campaign management through local MCP clients like Claude Code and Cursor.4079AGPL 3.0
- AlicenseAqualityDmaintenanceMCP server that wraps the Meta Marketing API (Graph API v25.0) as semantic tools for LLM agents.181MIT
- AlicenseAqualityDmaintenanceMCP server to manage Meta Ads (Facebook/Instagram) campaigns, ad sets, insights, and audiences from Claude Code using natural language.9MIT
- AlicenseNot gradedqualityDmaintenancePython MCP server that exposes Meta Marketing API data, providing tools to manage ad accounts, campaigns, and analytics through natural language interfaces.MIT