# Meta Ads MCP

把 Meta（Facebook）廣告 Graph API 包成 MCP server，給 Claude（Desktop / Claude Code）直接呼叫，公司同事就可以用對話的方式查廣告成效跟素材。

對應 PDF 規格的兩支 API：

| Tool | Endpoint | 用途 |
|---|---|---|
| `get_ad_insights` | `GET /{ad_account_id}/insights` (v23.0) | 抓花費、曝光、觸及、點擊、CTR/CPC/CPM、actions、影片觀看率等 |
| `get_ad_creative` | `GET /{ad_id}` (v25.0) | 抓單支廣告的素材（圖、文案、CTA、貼文連結） |

## 兩種跑法

| 模式 | 適用 | Transport |
|---|---|---|
| **stdio**（預設） | 本機 / 一個人用 / 開發 | Claude Desktop spawn 子程序 |
| **http** | EC2 / 容器 / 全公司共用 | streamable-http + Bearer auth |

---

# A. 本機（stdio）

## 安裝

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

## 接 Claude Desktop

編輯 `%APPDATA%\Claude\claude_desktop_config.json`：

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

重開 Claude Desktop → Settings → Developer 應該會看到 `meta-ads`。

---

# B. 部署到 EC2 給全公司用（http）

> 假設你已經有 EC2 + nginx + HTTPS 跑在 `https://ai.gastom.com.tw`。
> 我們不另外裝 Caddy，只跑 MCP 容器（綁 `127.0.0.1:8000`），讓你現有 nginx 把
> `https://ai.gastom.com.tw/meta-ads/*` 轉過去。

## 1. 產生共用 Bearer token

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

字串存好（密碼管理工具 / 公司 vault）。等下：
- 寫進 EC2 的 `.env`
- 發給同事填進 Claude Desktop

## 2. 把 code 放到 EC2

```bash
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. 啟動 MCP 容器

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

從 EC2 本機驗證（還沒透過 nginx）：

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

## 4. nginx 加一個 location

把 `deploy/nginx-meta-ads.conf` 的內容貼進你**現有的**
`server { listen 443 ssl; server_name ai.gastom.com.tw; ... }` 區塊裡，然後：

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

從外網驗證：

```bash
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. 同事的 Claude Desktop 設定

每位同事在 `%APPDATA%\Claude\claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`）加：

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

> 同事電腦要有 Node.js（`npx` 才能跑）。`mcp-remote` 在 stdio 跟你的 HTTPS endpoint 之間做轉接，他們**不需要**裝 Python / uv / 你的程式碼。

---

## 升級 / 更新流程

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

## 關掉

```bash
docker compose down
```

## Token 輪替

token 外洩或定期換新時：

1. EC2 上改 `.env` 的 `MCP_BEARER_TOKEN`
2. `docker compose up -d`（會 recreate mcp 容器）
3. 把新 token 發給同事，更新他們的 `claude_desktop_config.json`

---

## 對話範例

> 「幫我抓 2026-03-23 到 2026-03-25 的廣告數據，並列出花費前三的廣告」
>
> 「幫我看一下廣告 ID `120228265609960545` 用的素材長什麼樣子」

Claude 會自己決定先呼 `get_ad_insights`、再對特定 `ad_id` 呼 `get_ad_creative`。

## 安全注意事項

- **`.env` 永遠不要 commit**：`.gitignore` 已擋。
- **`MCP_BEARER_TOKEN` 是公司預算的鑰匙**：誰拿到都能呼叫 Meta API、燒你公司的廣告錢。當作 password 等級保管。
- **HTTPS 不可省略**：Bearer token 走 HTTP 等於明碼傳輸。
- **EC2 Security Group**：除了 80/443 對外，其他 port（特別是 22）建議鎖到公司 IP 範圍。