Meta MCP Connector

MCP-сервер на простом языке для Meta / Facebook Ads через Graph API.

Спрашивайте об аккаунтах, кампаниях, группах объявлений, расходах и эффективности на естественном языке — без необходимости знать имена таблиц или пути к API.

Возможности

• Живые данные из Facebook Marketing API (Graph API)

• Список рекламных аккаунтов с родительским Business Manager

• Эффективность кампаний / групп объявлений / объявлений (расходы, показы, клики, покупки)

• Панель расходов на уровне аккаунта (account-spend.html)

• OAuth для Claude.ai при развертывании на Cloud Run (MCP_PUBLIC_URL)

Related MCP server: Instagram Ads MCP Server

Структура проекта

meta-mcp-connector/
├── meta_mcp_server.py    # MCP server + HTTP routes + tools
├── meta_graph.py         # Facebook Graph API client
├── meta_oauth.py         # Claude-compatible OAuth provider
├── account-spend.html    # Spend-by-account dashboard
├── test-accounts.html    # Ad account list test page
├── get-token.html        # Helper to obtain FACEBOOK_ACCESS_TOKEN
├── requirements.txt
├── Dockerfile
├── deploy-cloudrun.ps1   # Deploy to Google Cloud Run
├── .env.example
└── .cursor/mcp.json      # Local Cursor MCP config (example)

Настройка (локально)

1. Клонирование и установка

git clone https://github.com/YOUR_USERNAME/meta-mcp-connector.git
cd meta-mcp-connector
python -m venv .venv

# Windows
.venv\Scripts\activate

pip install -r requirements.txt
copy .env.example .env

2. Настройка .env

FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_ACCESS_TOKEN=your_user_token_with_ads_read
FACEBOOK_AD_ACCOUNT_ID=114810198697538

Требования к токену

• Должен быть пользовательским токеном (EAA…), а не токеном приложения (app_id|secret)

• Создается в Graph API Explorer для вашего FACEBOOK_APP_ID

• Разрешения: ads_read, ads_management, business_management

Используйте get-token.html или запустите сервер и откройте http://127.0.0.1:8001/get-token.

3. Запуск сервера

python meta_mcp_server.py --http

4. Конфигурация MCP для Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "meta": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

Перезагрузите MCP в настройках Cursor после запуска сервера.

Инструменты MCP

Примеры запросов

• "Список моих рекламных аккаунтов Meta"

• "Сводка по рекламе Meta с 2026-08-01 по 2026-08-15"

• "Ежедневные расходы за последние 7 дней для WOW Ad Account"

• "Лучшие объявления по расходам за вчера"

• "Разбивка расходов по кампаниям за прошлую неделю"

Google Cloud Run

Разместите тот же HTTP MCP-эндпоинт на Cloud Run (та же схема, что и vdp-connector). Docker-образ не включает .env или секреты.

Предварительные требования

• Установленный и авторизованный Google Cloud SDK (gcloud) (gcloud auth login)

• Проект GCP с включенным биллингом

• Ваш Project ID в GCP

• Учетные данные Facebook в локальном .env (см. .env.example)

Развертывание

Из папки репозитория:

# App secret read from .env
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

# Optional overrides
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -Region "us-central1" -Service "meta-mcp"

# App secret from a one-line file (gitignored)
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -SecretFile ".\facebook-app-secret.key"

Что делает скрипт:

1. Включает Cloud Run, Cloud Build, Secret Manager, Artifact Registry

2. Загружает FACEBOOK_APP_SECRET → Secret Manager (meta-facebook-app-secret)

3. Загружает FACEBOOK_ACCESS_TOKEN → Secret Manager (meta-facebook-access-token), если он задан в .env

4. Развертывает с --source . (Dockerfile), переменными окружения и внедрением секретов

5. Устанавливает MCP_PUBLIC_URL в URL сервиса (требуется для OAuth Claude)

6. Выводит URL коннектора: https://SERVICE-URL/mcp

Флаги развертывания:

• --set-env-vars MCP_TRANSPORT=http,HOST=0.0.0.0,FACEBOOK_APP_ID=…,FACEBOOK_AD_ACCOUNT_ID=…

• --set-secrets FACEBOOK_APP_SECRET=meta-facebook-app-secret:latest,FACEBOOK_ACCESS_TOKEN=meta-facebook-access-token:latest

• --allow-unauthenticated (необходимо для рабочего MCP URL при первом развертывании)

• --session-affinity, --max-instances 1, --timeout 300, --port 8080

Cursor (Cloud Run)

После развертывания вставьте выведенный URL в .cursor/mcp.json:

"meta": {
  "url": "https://YOUR-CLOUD-RUN-URL/mcp"
}

При использовании Cloud Run не нужен локальный процесс python meta_mcp_server.py.

Пользовательский коннектор Claude

Claude.ai требует OAuth для удаленных пользовательских коннекторов. Этот сервер включает встроенный OAuth-провайдер, совместимый с Claude (Dynamic Client Registration), когда задан MCP_PUBLIC_URL (скрипт развертывания устанавливает его автоматически).

1. Разверните с помощью .\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

2. Удалите старый неработающий коннектор

3. Settings → Connectors → Add custom connector

4. Вставьте точно: https://YOUR-CLOUD-RUN-URL/mcp (обязательно с /mcp)

5. Оставьте OAuth Client ID пустым в дополнительных настройках (DCR включен)

6. Нажмите Connect — Claude зарегистрируется и кратко авторизуется

Если вы видите "Couldn't register with … sign-in service" (ofid_…):

• Убедитесь, что URL заканчивается на /mcp (не просто хост Cloud Run)

• Убедитесь, что сервис работает: откройте https://YOUR-CLOUD-RUN-URL/.well-known/oauth-authorization-server — вы должны увидеть JSON с registration_endpoint

• Убедитесь, что MCP_PUBLIC_URL соответствует источнику сервиса (повторно разверните, если изменили URL)

• Не вставляйте случайный OAuth Client ID, если вы не настроили внешний IdP

Проверка развертывания

Локально vs Cloud

Примечание по безопасности

--allow-unauthenticated делает URL Cloud Run публично доступным. OAuth означает, что Claude должен завершить регистрацию/авторизацию, прежде чем инструменты заработают; случайные вызывающие без токена получают 401. Тем не менее относитесь к URL как к чувствительному и добавьте более строгую аутентификацию перед широким распространением.

Частые проблемы

1. В URL Claude отсутствует /mcp → "Couldn't connect to the server"

2. MCP_PUBLIC_URL не задан → OAuth 404 → "Couldn't register with sign-in service"

3. Коммит .env или файлов с секретами

4. Забыли повторно развернуть после изменений в коде OAuth

5. Развертывание без FACEBOOK_ACCESS_TOKEN → Graph API возвращает ошибки разрешений

Публикация на GitHub

# Sign in to your new GitHub account first
git credential-manager github login --force

# Create repo on GitHub (browser or gh), then:
git remote add origin https://github.com/YOUR_USERNAME/meta-mcp-connector.git
git add .
git commit -m "Initial commit: Meta MCP connector"
git push -u origin main

Безопасность

• Никогда не коммитьте .env — он в gitignore

• FACEBOOK_ACCESS_TOKEN — секрет; ротируйте при утечке

• Развертывание Cloud Run использует --allow-unauthenticated для доступности MCP URL; OAuth защищает доступ к инструментам, когда задан MCP_PUBLIC_URL