Skip to main content
Glama
Meta Ads Codex MCP

Meta Ads Codex MCP

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

Available Tools

6 tools
meta_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

    B3.1/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      A 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.
      40
      79
      AGPL 3.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server to manage Meta Ads (Facebook/Instagram) campaigns, ad sets, insights, and audiences from Claude Code using natural language.
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Python MCP server that exposes Meta Marketing API data, providing tools to manage ad accounts, campaigns, and analytics through natural language interfaces.
      MIT