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.
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.
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
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.
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.The server looks for a token in this order:
META_ADS_MCP_ACCESS_TOKEN
~/.meta-ads-codex-mcp.json
~/.meta_ads_mcp_token.json from the local prototype helper
The config file is written with 0600 permissions.
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 serverinstall-codex runs:
codex mcp add meta_ads_codex -- meta-ads-codex-mcp serverYou can remove it with:
codex mcp remove meta_ads_codexTreat 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.
Run the server locally:
node src/cli.js serverRun a direct check:
node src/cli.js checkRead-only. Get account-level performance summary for a date preset.
| Name | Required | Description | Default |
|---|---|---|---|
| date_preset | No | Defaults to last_30d. | |
| ad_account_id | No | ||
| advertiser_request | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only', which is valuable, but it does not describe what data is returned, potential errors, or permissions required. The read-only flag adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences with no redundant information. It front-loads the read-only nature and gets straight to the resource and temporal scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and 3 undocumented parameters. The description does not explain what constitutes an 'account-level performance summary' (e.g., metrics, dimensions) nor clarify how the optional parameters affect the result. The description is too sparse for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, with only date_preset having a description. The description mentions 'date preset' but adds no meaning beyond the schema. The ad_account_id and advertiser_request parameters are completely unexplained, and the description does not compensate for this gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource as 'account-level performance summary' with a date preset. This distinguishes it from siblings like meta_ads_ad_performance (ad-level) and meta_ads_total_spend (metric-level).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus the sibling tools. It only states what it does without mentioning alternatives or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only. List active ads and their performance for the default or supplied ad account.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| date_preset | No | Meta date preset such as today, yesterday, last_7d, last_30d, maximum. | |
| ad_account_id | No | ||
| advertiser_request | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states 'Read-only' and the action, but omits details about performance metrics, pagination, active-ad filtering semantics, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. 'Read-only' is placed first, immediately conveying safety, and the rest is concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is too sparse. It lacks parameter explanations, usage context, and behavioral details that an agent would need for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 25% (only date_preset has a schema description). The description hints that ad_account_id can be defaulted or supplied, but it does not explain limit or advertiser_request, leaving these parameters ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear action (list) and resource (active ads and their performance). It is specific enough to understand the core function, but it does not explicitly differentiate itself from siblings like meta_ads_ad_performance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The phrase 'for the default or supplied ad account' gives parameter context but does not establish selection criteria or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only. Get performance for one ad by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| ad_id | Yes | ||
| date_preset | No | ||
| ad_account_id | No | ||
| advertiser_request | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly labels the tool as 'Read-only', which is a useful safety trait given no annotations are provided. However, it offers no details on return format, metrics, date ranges, or API limitations, leaving significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise with the critical safety qualifier 'Read-only' placed first, followed by a clear action statement. No filler words; every element contributes to immediate comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters, no output schema, and no annotations, the description is too sparse. It fails to specify what performance metrics are returned, how date_preset affects results, whether ad_account_id is necessary, or how this differs from performance_trend, leaving agents to guess critical execution context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, and the description only explains ad_id via 'by ID'. The other three parameters (date_preset, ad_account_id, advertiser_request) are left completely unspecified, so the description fails to compensate for the schema's lack of semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches performance data for a single ad specified by ID. The phrase 'one ad by ID' differentiates it from sibling tools like performance_trend, which likely cover multiple ads or periods.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no guidance on when to use this tool versus alternatives such as meta_ads_performance_trend or meta_ads_account_summary. The description implies single-ad lookups but does not state exclusions or scenarios where siblings are preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only. List Meta ad accounts available to the authenticated user.
| Name | Required | Description | Default |
|---|---|---|---|
| advertiser_request | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the read-only nature and authentication scope, which is useful. However, it omits further behavioral details such as response format, pagination, or potential errors, so transparency remains minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, containing only two short sentences with 'Read-only' front-loaded. Every word contributes to the meaning, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core purpose is clear, but the opaque parameter and lack of differentiation from sibling tools make the description insufficient for an agent to confidently invoke the tool correctly in all contexts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'advertiser_request' has no schema description and is not explained in the tool description. With 0% schema coverage and no compensating explanation, the agent has no semantic guidance for this parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and clearly identifies the resource ('Meta ad accounts') and scope ('available to the authenticated user'). This distinguishes it from sibling tools that focus on ad performance, spend, or summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the agent needs to enumerate available ad accounts, but it does not explicitly state when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions beyond authentication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only. Ask Meta's insight tool for performance trend analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| entity_ids | No | ||
| ad_account_id | No | ||
| analysis_level | No | ||
| analysis_metric | No | ||
| advertiser_request | No | ||
| conversation_topic | No | ||
| conversation_intent | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses 'Read-only,' which is a useful safety trait given there are no annotations. However, it provides no other behavioral context, such as return format, data granularity, rate limits, or what 'trend analysis' entails. With annotations absent, this is insufficient disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, but this is under-specification rather than conciseness. While it is front-loaded with the read-only note, the core phrase 'performance trend analysis' adds little beyond the tool name and fails to provide meaningful structure or context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 undocumented parameters, no output schema, no annotations, and a one-sentence description, the tool is severely incomplete. Nothing explains how to construct a request, what results look like, or how this fits with the broader Meta Ads tool family.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 7 parameters with 0% description coverage, and the tool description does not explain any of them. Entity IDs, ad_account_id, metrics, and other fields are left entirely undefined, so an agent has no idea what values to supply or what they control.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool is for 'performance trend analysis,' which is a clear function but remains vague about the specific output or scope. It does not distinguish this from sibling tools like meta_ads_ad_performance, which likely also deals with performance metrics. The purpose is acceptable but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool instead of alternatives like meta_ads_ad_performance or meta_ads_account_summary. The description simply says 'Ask Meta's insight tool,' which does not convey any usage context, exclusions, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read-only. Get total account spend for the default or supplied ad account.
| Name | Required | Description | Default |
|---|---|---|---|
| date_preset | No | Defaults to maximum. | |
| ad_account_id | No | ||
| advertiser_request | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states 'Read-only,' which is an important behavioral disclosure given that no annotations are provided. It also implies fallback to a default account. However, it does not describe the output format, error handling, or behavior regarding date_preset, which would be beneficial given the lack of annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is efficient and front-loaded. Every element ('Read-only', 'total account spend', 'default or supplied ad account') adds or clarifies meaning without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description should explain what is returned and how parameters affect results. It fails to mention return value structure or the role of date_preset and advertiser_request, leaving significant context gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 33%, the description must compensate for undocumented parameters. It only hints at ad_account_id ('supplied ad account') but leaves date_preset and advertiser_request unexplained. This is insufficient given the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get total account spend for the default or supplied ad account.' The verb 'Get' and resource 'total account spend' are specific, and 'default or supplied ad account' adds scope, distinguishing it from sibling tools like meta_ads_account_summary (which likely provides a broader summary).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: whenever total spend for an ad account is needed. It notes the default vs. supplied account behavior, which is useful. However, it does not explicitly mention alternative tools or exclusions, so it misses the top tier of guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0meta_ads_account_summarymeta_ads_active_adsmeta_ads_ad_performancemeta_ads_list_accountsmeta_ads_performance_trendmeta_ads_total_spendScored 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.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Hosted MCP server for live public-data APIs and Skills for AI agents.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Google Ads MCP server — manage campaigns, keywords, and metrics.
