# FB Ads MCP Server

MCP server sendiri yang bagi Claude akses terus ke data Facebook Ads (Meta Ads) kau —
tanpa perlu bayar Supermetrics/Windsor.ai.

Ada 3 tools:
- `list_campaigns` — senarai campaign (active/paused/all)
- `get_campaign_insights` — spend, impressions, clicks, CPC, CTR ikut campaign
- `get_account_spend_summary` — ringkasan total spend untuk seluruh akaun

---

## 1. Dapatkan Facebook Access Token

1. Pergi ke [Meta Business Suite](https://business.facebook.com) → **Business Settings**
2. Bawah **Users**, pilih **System Users** → **Add** → buat satu system user (contoh: `mcp-bot`)
3. Assign system user tu ke Ad Account kau, dengan permission **Manage Campaigns** (view sudah cukup untuk `ads_read`)
4. Klik **Generate New Token**:
   - App: pilih/buat Facebook App (kena ada App ID di [developers.facebook.com](https://developers.facebook.com))
   - Permission: tick `ads_read`
   - Token expiry: pilih **Never expire** (system user token boleh permanent)
5. Copy token tu — ni akan jadi `FB_ACCESS_TOKEN`
6. Dapatkan Ad Account ID kau dari Business Settings → Accounts → Ad Accounts (format: `act_1234567890`)

## 2. Setup Local (untuk test dulu)

```bash
npm install
cp .env.example .env.local
# isi FB_ACCESS_TOKEN, FB_AD_ACCOUNT_ID, dan MCP_SECRET (guna: openssl rand -hex 24)
npm run dev
```

Server akan jalan di `http://localhost:3000/mcp?key=MCP_SECRET_KAU`

## 3. Deploy ke Vercel

```bash
npm i -g vercel
vercel
```

Lepas deploy, pergi ke **Vercel Dashboard → Project → Settings → Environment Variables**,
tambah `FB_ACCESS_TOKEN`, `FB_AD_ACCOUNT_ID`, `MCP_SECRET` (yang sama macam local), then
`vercel --prod` untuk deploy production.

URL server kau akan jadi macam:
```
https://fb-ads-mcp-xxxx.vercel.app/mcp?key=MCP_SECRET_KAU
```

## 4. Connect ke Claude

1. Claude → **Settings → Connectors → Add custom connector**
2. Paste URL penuh (dengan `?key=...` sekali) dari step 3
3. Klik **Add**
4. Dalam mana-mana chat, klik **+** → **Add connectors** → toggle ON connector ni
5. Cuba tanya: *"Tunjuk spend campaign aku 7 hari lepas"*

## Nota Keselamatan

- Server ni public di internet (syarat MCP remote connector). `MCP_SECRET` di URL adalah
  satu-satunya proteksi — jangan share URL tu kat sesiapa, treat macam password.
- Token Facebook kau disimpan sebagai environment variable di Vercel, bukan dalam kod — jangan
  commit `.env.local` ke Git (dah ada dalam `.gitignore` sepatutnya, cek balik).
- Kalau nak lebih selamat, boleh upgrade guna OAuth (Claude custom connector ada slot untuk
  OAuth Client ID/Secret) — tapi untuk penggunaan solo/peribadi, shared secret ni dah cukup.