gravity-ads-mcp

Локальный MCP-сервер для API рекламного кабинета Gravity. Создавайте, редактируйте, ставьте на паузу и архивируйте кампании — и получайте всю аналитику — из любого агента, поддерживающего MCP, не выпуская ваш API-ключ за пределы вашей машины.

Gravity предоставляет размещённый MCP-сервер по адресу https://platform.trygravity.ai/mcp, но он только для чтения. Этот пакет оборачивает полный API Gravity Dashboard (включая создание и редактирование) в локальный MCP-сервер на stdio, который запускается через npx, поэтому запросы идут напрямую с вашего компьютера на platform.trygravity.ai — ничего не проходит через третьи стороны.

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

• Node.js ≥ 18 (проверьте командой node --version)

• npx (входит в состав npm; поставляется с Node)

• API-ключ рекламодателя Gravity — получите его на https://app.trygravity.ai в разделе Settings → API Key

Related MCP server: Google Ads MCP Worker

Быстрый старт

Добавьте следующее в файл конфигурации вашего MCP-клиента. Замените your-gravity-api-key на ваш реальный ключ.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gravity": {
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

Пользователям Windows: Если npx не найден, попробуйте "command": "cmd" с "args": ["/c", "npx", "-y", "gravity-ads-mcp"].

Claude Code

Создайте файл .mcp.json в корне проекта (или добавьте в ~/.claude/mcp.json для глобальной конфигурации):

{
  "mcpServers": {
    "gravity": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

Или добавьте через CLI:

claude mcp add gravity --env GRAVITY_API_KEY=your-gravity-api-key -- npx -y gravity-ads-mcp

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "gravity": {
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

opencode

opencode.json в корне проекта:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gravity": {
      "type": "local",
      "command": ["npx", "-y", "gravity-ads-mcp"],
      "environment": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

Примечание: opencode использует "environment" (не "env").

Windsurf

~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gravity": {
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

Другие клиенты

Любой MCP-клиент, поддерживающий JSON-формат mcpServers (той же структуры, что и Claude Desktop), может использовать этот сервер. Добавьте следующее в файл конфигурации MCP вашего клиента:

{
  "mcpServers": {
    "gravity": {
      "command": "npx",
      "args": ["-y", "gravity-ads-mcp"],
      "env": {
        "GRAVITY_API_KEY": "your-gravity-api-key"
      }
    }
  }
}

Переменные окружения

Инструменты

Аккаунт

Кампании

Группы объявлений и объявления

Отчётность

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

После настройки попробуйте попросить вашего агента:

• "Список моих активных кампаний"

• "Какой у меня ROAS за последние 14 дней?"

• "Создай кампанию 'Летняя распродажа' с бюджетом $100/день, таргетинг на US и CA, используя генеративную группу объявлений для кроссовок"

• "Поставь на паузу все кампании с расходом более $500"

• "Покажи эффективность групп объявлений для кампании camp-456 за последние 7 дней в America/New_York"

• "Создай ручную группу объявлений с такими объявлениями: заголовок 'Скидка 50% на кроссовки', текст 'Летняя распродажа на все кроссовки.', CTA 'Купить сейчас'"

• "Какие конверсии я получил вчера?"

• "Создай пиксель для https://acme.com"

Безопасность и конфиденциальность

• Ваш GRAVITY_API_KEY передаётся как переменная окружения процесса и никогда не логируется и не передаётся на какой-либо сервер, кроме platform.trygravity.ai.

• Все API-запросы идут напрямую с вашей машины к API Gravity — без посредников.

• Запуск через npx означает отсутствие глобальной установки; сервер запускается заново в каждой сессии.

• Вы можете перегенерировать ключ в любое время на https://app.trygravity.ai в разделе Settings → API Key.

Устранение неполадок

Участники

Инструкции по локальной настройке, сборке, тестированию и публикации см. в DEVELOPMENT.md.

Лицензия

MIT