Meta Ads MCP

Обёртка над Graph API Meta (Facebook) в виде MCP-сервера для прямого вызова из Claude (Desktop / Claude Code), чтобы коллеги могли запрашивать эффективность рекламы и креативы в диалоговом режиме.

Два API, соответствующих спецификации в PDF:

Два способа запуска

A. Локально (stdio)

Related MCP server: Meta Ads MCP Server

Установка

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:

{
  "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-токена

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

Сохраните строку (менеджер паролей / корпоративный vault). Далее:

• Запишите её в .env на EC2

• Раздайте коллегам для заполнения в Claude Desktop

2. Размещение кода на 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. Запуск контейнера MCP

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

Проверка с самого EC2 (ещё не через 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. Добавление location в nginx

Вставьте содержимое deploy/nginx-meta-ads.conf в ваш существующий блок server { listen 443 ssl; server_name ai.gastom.com.tw; ... }, затем:

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

Проверка из внешней сети:

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

{
  "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-эндпоинтом — им не нужно устанавливать Python / uv / ваш код.

Процесс обновления

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

Остановка

docker compose down

Ротация токена

При утечке токена или плановой замене:

1. Измените MCP_BEARER_TOKEN в .env на EC2

2. Выполните docker compose up -d (контейнер mcp будет пересоздан)

3. Раздайте новый токен коллегам и обновите их claude_desktop_config.json

Примеры диалогов

«Собери данные по рекламе за 2026-03-23 — 2026-03-25 и выведи три объявления с наибольшими расходами»

«Покажи, какой креатив используется в объявлении с ID 120228265609960545»

Claude сам решит сначала вызвать get_ad_insights, а затем get_ad_creative для конкретного ad_id.

Меры безопасности

• Никогда не коммитьте .env: он уже добавлен в .gitignore.

• MCP_BEARER_TOKEN — это ключ к бюджету компании: любой, кто его получит, сможет вызывать Meta API и тратить деньги компании на рекламу. Храните его как пароль.

• HTTPS обязателен: передача Bearer-токена по HTTP равносильна передаче в открытом виде.

• Security Group на EC2: кроме 80/443 наружу, остальные порты (особенно 22) рекомендуется ограничить диапазоном IP-адресов компании.