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.

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 set

Optionally set your default ad account:

meta-ads-codex-mcp account set 2051892919047874

Install the MCP server into Codex:

meta-ads-codex-mcp install-codex

Restart 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:

1. META_ADS_MCP_ACCESS_TOKEN
2. ~/.meta-ads-codex-mcp.json
3. ~/.meta_ads_mcp_token.json from 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 server

Codex Config

install-codex runs:

codex mcp add meta_ads_codex -- meta-ads-codex-mcp server

You can remove it with:

codex mcp remove meta_ads_codex

Security

• 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 server

Run a direct check:

node src/cli.js check