# Meta Ads Codex MCP

A local MCP server that lets Codex answer conversational questions about Meta Ads performance.

Example prompts in Codex:

```text
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:

```bash
npm install -g .
```

Store a token:

```bash
meta-ads-codex-mcp token set
```

Optionally set your default ad account:

```bash
meta-ads-codex-mcp account set 2051892919047874
```

Install the MCP server into Codex:

```bash
meta-ads-codex-mcp install-codex
```

Restart Codex, then ask:

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

```bash
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:

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

You can remove it with:

```bash
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:

```bash
node src/cli.js server
```

Run a direct check:

```bash
node src/cli.js check
```