GrowthBook

GrowthBook MCP Thin

Тонкий MCP-сервер для GrowthBook с четырьмя инструментами:

Инструмент	Назначение
growthbook_list_skills	Список встроенных навыков агента GrowthBook (имя + описание)
growthbook_read_skill	Возвращает полный markdown навыка (рабочий процесс + ограничения)
growthbook_api_read	Аутентифицированный GET-прокси к API GrowthBook
growthbook_api_write	Аутентифицированный POST/PUT/PATCH/DELETE-прокси

Компетенции находятся в репозитории skills и встраиваются во время сборки. Возможности разделены на инструменты API для чтения и записи (без форматтеров для отдельных конечных точек), чтобы клиенты могли корректно учитывать readOnlyHint / destructiveHint.

Инструменты имеют префикс growthbook_, чтобы оставаться однозначными, когда у клиента загружено несколько MCP-серверов.

Установка / запуск

npm install
npm run build

Укажите вашему MCP-клиенту на скомпилированную точку входа:

{
  "mcpServers": {
    "growthbook": {
      "command": "node",
      "args": ["/absolute/path/to/growthbook-mcp/server/index.js"],
      "env": {
        "GB_API_KEY": "your_api_key_or_pat",
        "GB_API_URL": "https://api.growthbook.io"
      }
    }
  }
}

Или запустите опубликованный пакет:

npx @growthbook/mcp

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

Переменная	Обязательная	По умолчанию	Назначение
GB_API_KEY	Да для stdio; необязательно для HTTP OAuth	—	Ключ API GrowthBook или персональный токен доступа
GB_API_URL	Нет	https://api.growthbook.io	Базовый URL API (self-hosted) и издатель AS по умолчанию для OAuth
GB_MCP_TRANSPORT	Нет	stdio	stdio или http
GB_MCP_PORT	Нет	3333	Порт прослушивания HTTP (когда transport=http)
GB_MCP_HOST	Нет	127.0.0.1	Хост привязки HTTP
GB_MCP_URL	Да для HTTP	—	Публичный базовый URL MCP, встраиваемый в метаданные ресурса OAuth (сервер отказывается запускаться в HTTP-режиме без него)
GB_OAUTH_ISSUER	Нет	GB_API_URL	URL издателя AS OAuth GrowthBook
GB_HTTP_HEADER_*	Нет	—	Дополнительные заголовки запросов (например, GB_HTTP_HEADER_CF_ACCESS_TOKEN)
GB_SKILLS_ENABLED	Нет	true	Установите в false / 0, чтобы отключить инструменты навыков

Режим HTTP + OAuth

OAUTH_AS_ENABLED=1  # on the GrowthBook API
GB_MCP_TRANSPORT=http GB_API_URL=http://localhost:3100 GB_MCP_PORT=3333 npm start

Клиенты подключаются к:

• http://127.0.0.1:3333/mcp — полный (навыки + чтение/запись API)
• http://127.0.0.1:3333/mcp/api — только возможности (growthbook_api_read + growthbook_api_write)

Неаутентифицированные запросы получают 401 с WWW-Authenticate, указывающим на /.well-known/oauth-protected-resource, который рекламирует сервер авторизации GrowthBook.

Перед обработкой MCP сервер проверяет REST API GrowthBook (GET /api/v1/) с помощью bearer-токена. 401 от этой проверки (или позже от инструмента API) приводит к HTTP 401 с error="invalid_token", чтобы MCP-клиент мог обновить токен — вместо отображения "This API key has expired" как ошибки инструмента. 403 рассматривается как принятый bearer-токен (отказ в доступе ≠ недействительный токен), чтобы клиенты не попадали в цикл обновления.

Режим только возможностей

HTTP (рекомендуется для удалённого доступа): укажите клиенту на /mcp/api вместо /mcp:

{
  "mcpServers": {
    "growthbook": {
      "url": "http://127.0.0.1:3333/mcp/api"
    }
  }
}

Путь	Инструменты
/mcp	growthbook_list_skills, growthbook_read_skill, growthbook_api_read, growthbook_api_write (если не GB_SKILLS_ENABLED=false)
/mcp/api	только growthbook_api_read, growthbook_api_write

stdio / на уровне процесса: задайте переменные окружения, чтобы навыки никогда не регистрировались:

"env": {
  "GB_API_KEY": "...",
  "GB_SKILLS_ENABLED": "false"
}

Когда навыки отключены, регистрируются только инструменты чтения/записи API. growthbook_list_skills и growthbook_read_skill не предоставляются.

Как встраиваются навыки

npm run build   # tsc && bundle-skills

scripts/bundle-skills.mjs копирует каждый skills/*/SKILL.md из канонического репозитория навыков в server/skills/<name>.md.

Определение исходного пути:

1. Переменная окружения SKILLS_SRC (путь к корню репозитория навыков), или
2. ../skills (соседняя директория)

Репозиторий навыков остаётся источником истины — этот пакет никогда не форкает содержимое навыков.

Использование навыков с инструментами API

Встроенные навыки по-прежнему показывают рабочие процессы как:

gb-call GET /api/v1/projects
gb-call POST /api/v2/features ./payload.json

Этот MCP-сервер не вызывает gb-call из командной строки. Сопоставьте GET → growthbook_api_read и POST/PUT/PATCH/DELETE → growthbook_api_write с тем же путём и необязательной строкой JSON-тела. Инструкции сервера и вывод growthbook_read_skill содержат это примечание о мосте.

Детали инструментов

growthbook_api_read / growthbook_api_write

{ "path": "/api/v1/projects" }
{ "method": "POST", "path": "/api/v2/features", "body": "{\"id\":\"my-flag\",...}" }

• Чтение: только GET (readOnlyHint: true)
• Запись: POST | PUT | PATCH | DELETE (destructiveHint: true)
• Возвращает необработанное тело ответа при 2xx
• При не-2xx возвращает информативную ошибку (isError: true), охватывающую сбои аутентификации, подсказки для self-hosted 404 и ограничения частоты запросов
• Свободные пути нацелены на REST API GrowthBook

growthbook_list_skills / growthbook_read_skill

Регистрируются только когда GB_SKILLS_ENABLED не отключён. growthbook_read_skill возвращает полное содержимое SKILL.md, чтобы агент мог следовать шагам рабочего процесса и ограничениям.

Разработка

# Requires a sibling checkout at ../skills (or SKILLS_SRC)
npm install
npm run build
npm start

Автономный HTTP-режим

По умолчанию сервер работает через stdio. Установите GB_MCP_TRANSPORT=http, чтобы запустить его как автономный HTTP-сервер, который предоставляет MCP на /mcp (навыки + инструменты API) и /mcp/api (только возможности), за поверхностью защищённого ресурса OAuth 2.0 (метаданные RFC 9728 + RFC 6750 WWW-Authenticate).

• GB_MCP_URL (обязателен в HTTP-режиме) — публичный базовый URL сервера. Он встраивается в ресурс OAuth (audience) и метаданные защищённого ресурса, поэтому никогда не выводится из заголовков запросов. Сервер отказывается запускаться без него.
• GB_MCP_PORT (по умолчанию 3333) и GB_MCP_HOST (по умолчанию 127.0.0.1).
• Входящие bearer-токены проверяются через запрос к REST API GrowthBook; отклонённый токен получает HTTP 401 + WWW-Authenticate, чтобы клиент мог обновить его.

Запускайте его в доверенной сети или привязанным к loopback. Для мультитенантного или публичного развёртывания разместите перед ним собственный шлюз/аутентификацию.

Релизы

Выпуск релиза — осознанный шаг: увеличьте версию в package.json, затем отправьте соответствующий тег v*:

git tag v2.0.0
git push origin v2.0.0

Этот тегированный коммит (с навыками, зафиксированными на момент релиза) публикует:

• @growthbook/mcp в npm — пререлизы (версии с -, например 2.0.0-beta.1) попадают под dist-tag beta; стабильные версии становятся latest
• мультиархитектурный (amd64 + arm64) образ в ghcr.io/growthbook/growthbook-mcp (:<version>, плюс :<major>, :<major>.<minor> и :latest для стабильных релизов)
• запись в реестре MCP
• релиз на GitHub

Установите релиз с помощью npx @growthbook/mcp@<version> или загрузите ghcr.io/growthbook/growthbook-mcp:<version>.