Meta Ads MCP

Wrap the Meta (Facebook) Ads Graph API as an MCP server for Claude (Desktop / Claude Code) to call directly, so colleagues can query ad performance and creatives through conversation.

The two APIs corresponding to the PDF spec:

Two ways to run

A. Local (stdio)

Related MCP server: Meta Ads MCP Server

Installation

cd C:\Users\bexo6\OneDrive\桌面\mcp_meta_claude
uv sync
Copy-Item .env.example .env   # 然後填好 META_ACCESS_TOKEN 等

Connect to Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\bexo6\\OneDrive\\桌面\\mcp_meta_claude",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Restart Claude Desktop → Settings → Developer should show meta-ads.

B. Deploy to EC2 for company-wide use (http)

Assuming you already have EC2 + nginx + HTTPS running at https://ai.gastom.com.tw. We won't install Caddy separately; we only run the MCP container (bound to 127.0.0.1:8000), and let your existing nginx proxy https://ai.gastom.com.tw/meta-ads/* to it.

1. Generate a shared Bearer token

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Save the string (password manager / company vault). Next:

• Write it into EC2's .env

• Distribute it to colleagues to fill into Claude Desktop

2. Put the code on EC2

ssh your-user@ec2-host
git clone <你的 repo 位置> meta-ads-mcp
cd meta-ads-mcp

cat > .env <<'EOF'
META_ACCESS_TOKEN=<長效 Graph API token>
META_AD_ACCOUNT_ID=act_870176260326362
MCP_BEARER_TOKEN=<上一步產生的字串>
EOF
chmod 600 .env

3. Start the MCP container

docker compose up -d --build
docker compose logs -f mcp     # 看到 "Uvicorn running on http://0.0.0.0:8000" 就 OK

Verify from the EC2 host itself (not yet through nginx):

curl -i http://127.0.0.1:8000/healthz                # 200
curl -i -X POST http://127.0.0.1:8000/mcp            # 401（沒 token）

4. Add a location block to nginx

Paste the contents of deploy/nginx-meta-ads.conf into your existing server { listen 443 ssl; server_name ai.gastom.com.tw; ... } block, then:

sudo nginx -t                # 語法檢查
sudo systemctl reload nginx  # 套用

Verify from the external network:

curl -i https://ai.gastom.com.tw/meta-ads/healthz                  # 200
curl -i -X POST https://ai.gastom.com.tw/meta-ads/mcp              # 401
curl -i -X POST -H "Authorization: Bearer <你的token>" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
     https://ai.gastom.com.tw/meta-ads/mcp                          # 200 + serverInfo

5. Colleagues' Claude Desktop configuration

Each colleague adds to %APPDATA%\Claude\claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://ai.gastom.com.tw/meta-ads/mcp",
        "--header",
        "Authorization: Bearer 上面產生的_MCP_BEARER_TOKEN"
      ]
    }
  }
}

Colleagues' machines need Node.js (so npx can run). mcp-remote bridges between stdio and your HTTPS endpoint; they don't need to install Python / uv / your code.

Upgrade / update process

cd /path/to/meta-ads-mcp
git pull
docker compose up -d --build

Shut down

docker compose down

Token rotation

When the token leaks or needs periodic rotation:

1. Change MCP_BEARER_TOKEN in .env on EC2

2. docker compose up -d (will recreate the mcp container)

3. Distribute the new token to colleagues and update their claude_desktop_config.json

Conversation examples

"Fetch ad data from 2026-03-23 to 2026-03-25 and list the top 3 ads by spend"

"Show me what the creative for ad ID 120228265609960545 looks like"

Claude will decide on its own to call get_ad_insights first, then call get_ad_creative for the specific ad_id.

Security notes

• Never commit .env: .gitignore already blocks it.

• MCP_BEARER_TOKEN is the key to the company budget: anyone who gets it can call the Meta API and burn your company's ad spend. Treat it with password-level care.

• HTTPS is not optional: sending the Bearer token over HTTP is equivalent to plaintext transmission.

• EC2 Security Group: besides 80/443 being open to the outside, restrict other ports (especially 22) to the company IP range.