GrowthBook

GrowthBook MCP Thin

GrowthBook용 경량 MCP 서버로, 네 가지 도구를 제공합니다:

도구	용도
growthbook_list_skills	최상위 스킬 진입점 목록 (이름 + 설명)
growthbook_read_skill	나열된 스킬 또는 자격을 갖춘 하위 워크플로우 반환 (feature-flags 또는 feature-flags/references/flag-create)
growthbook_api_read	GrowthBook API에 대한 인증된 GET 패스스루
growthbook_api_write	인증된 POST/PUT/PATCH/DELETE 패스스루

역량은 skills 저장소에 있으며 빌드 시점에 번들링됩니다. 기능은 읽기/쓰기 API 도구로 분리되어(엔드포인트별 포맷터 없음) 클라이언트가 readOnlyHint / destructiveHint을 올바르게 준수할 수 있습니다.

도구에는 growthbook_ 접두사가 붙어 클라이언트에 여러 MCP 서버가 로드된 경우에도 모호함이 없습니다.

Cursor 플러그인

Cursor Marketplace에서 GrowthBook을 설치하세요. 플러그인은 Cursor를 https://mcp.growthbook.io/mcp의 호스팅 서버에 연결합니다. 첫 번째 도구 호출 시 GrowthBook 로그인이 열려 권한을 부여합니다. 자체 호스팅 GrowthBook 사용자는 아래 설명대로 서버를 수동으로 구성해야 합니다.

플러그인은 .cursor-plugin/plugin.json 및 mcp.json으로 정의됩니다. 변경 사항을 로컬에서 테스트하려면 저장소를 ~/.cursor/plugins/local/growthbook에 복사하고 Developer: Reload Window를 실행하세요.

설치 / 실행

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의 경우 선택	—	GrowthBook API 키 또는 개인 액세스 토큰
GB_API_URL	아니요	https://api.growthbook.io	API 기본 URL(자체 호스팅) 및 기본 OAuth AS 발급자
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의 경우 필수	—	OAuth 리소스 메타데이터에 기록되는 공개 MCP 기본 URL(이 값 없이는 HTTP 모드에서 서버가 시작되지 않음)
GB_MCP_KEEP_ALIVE_TIMEOUT_MS	아니요	90000	HTTP 모드의 유휴 keep-alive 시간 초과. 앞단의 로드 밸런서 유휴 시간 초과보다 커야 합니다. 그렇지 않으면 LB가 서버가 이미 닫은 연결을 재사용하여 요청이 502로 실패할 수 있습니다
OPENAI_APPS_CHALLENGE_TOKEN	아니요	—	OpenAI 플러그인 도메인 검증을 위해 /.well-known/openai-apps-challenge에서 일반 텍스트로 제공(HTTP 모드). 설정되지 않으면 경로가 404를 반환
GB_OAUTH_ISSUER	아니요	GB_API_URL	GrowthBook OAuth AS 발급자 URL
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 Authorization Server를 광고합니다.

MCP를 처리하기 전에 서버는 베어러로 GrowthBook REST(GET /api/v1/)를 프로브합니다. 해당 프로브(또는 이후 API 도구)에서 401이 발생하면 HTTP 401와 error="invalid_token"을 반환하여 MCP 클라이언트가 새로 고칠 수 있게 합니다. "This API key has expired"를 도구 오류로 표시하는 대신 말입니다. 403는 허용된 베어러로 처리됩니다(권한 거부 ≠ 잘못된 토큰) — 클라이언트가 새로 고침 루프에 빠지지 않도록 합니다.

기능 전용 모드

HTTP(원격에 권장): /mcp 대신 /mcp/api을 클라이언트에 지정하세요:

{
  "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>/SKILL.md                   → server/skills/<skill>/SKILL.md
skills/<skill>/references/<workflow>.md   → server/skills/<skill>/references/<workflow>.md

소스 경로 해석:

1. SKILLS_SRC 환경 변수(스킬 저장소 루트 경로)
2. agent-skills.local.json — { "path": "../skills" }, 저장소 루트 기준. Gitignore 처리됨. agent-skills.local.json.example 복사
3. skills-src/ — CI 및 Docker 빌드가 공급하는 것

암시적 형제 조회는 없습니다. ../skills는 해당 경로에 있는 무엇이든 해석하므로 로컬 빌드가 CI가 빌드하는 커밋과 조용히 달라질 수 있습니다.

CI, 클라우드 배포 및 릴리스는 모두 agent-skills.lock.json을 읽고 해당 정확한 스킬 커밋을 체크아웃합니다. 업스트림 스킬 변경 사항을 배포하려면 잠금 파일의 커밋을 업데이트하세요. 로컬 개발은 agent-skills.local.json 또는 SKILLS_SRC으로 모든 체크아웃을 가리킬 수 있습니다.

스킬 저장소는 진실의 원천으로 유지됩니다 — 이 패키지는 스킬 콘텐츠의 포크를 유지하지 않습니다. bundle-skills.mjs의 작은 블록리스트에 있는 스킬을 제외하고 새 스킬은 자동으로 흐릅니다. 현재 gb-setup만 차단됩니다. GrowthBook 자체가 아닌 gb-call 셸 어댑터를 구성하기 때문입니다.

스킬별 scripts/ 디렉터리는 복사되지 않습니다. 상대 `references/foo.md` 링크는 자격을 갖춘 `feature-flags/references/foo` paths so growthbook_read_skill로 다시 작성되어 해석할 수 있습니다.

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가 아닌 경우 인증 실패, 자체 호스팅 404 힌트 및 속도 제한을 포함한 실행 가능한 오류(isError: true) 반환
• 자유 형식 경로는 GrowthBook REST API를 대상으로 함
• 각 요청에는 MCP 사용 헤더가 포함됨(사용 원격 측정 참조)

growthbook_list_skills / growthbook_read_skill

GB_SKILLS_ENABLED이 비활성화되지 않은 경우에만 등록됩니다.

• growthbook_list_skills는 최상위 스킬 진입점을 반환합니다. 항목에는 완전한 워크플로우가 포함되거나 하위 워크플로우로 연결될 수 있습니다.
• growthbook_read_skill은 나열된 최상위 이름 또는 로드된 스킬이 명명한 자격을 갖춘 하위 경로(feature-flags/references/flag-create)를 허용하고 전체 마크다운(워크플로우 + 가드레일)을 반환합니다.

사용 원격 측정

이 서버는 자체적으로 원격 측정을 어디에도 보내지 않습니다. 대신 growthbook_api_read / growthbook_api_write이 수행하는 모든 REST 호출에는 GrowthBook 인스턴스에 해당 호출이 MCP에서 왔음을 알리는 헤더가 포함됩니다:

헤더	예시	내용
X-GB-MCP-Tool	growthbook_api_read	호출을 수행한 도구
X-GB-MCP-Version	2.2.0	이 서버의 버전
X-GB-MCP-Transport	stdio	stdio 또는 http
X-GB-MCP-Client	cursor/1.2.3	initialize 핸드셰이크의 MCP 클라이언트 이름/버전 또는 HTTP 모드의 User-Agent

GrowthBook은 기존 제품 원격 측정을 통해 이를 기록하므로 동일한 제어가 적용됩니다. 자체 호스팅 인스턴스에서 GrowthBook 백엔드에 DISABLE_TELEMETRY을 설정하면 GrowthBook의 나머지 원격 측정과 함께 이 기능이 꺼집니다. 이전 GrowthBook 버전은 헤더를 무시합니다. 스킬 도구(growthbook_list_skills / growthbook_read_skill)는 로컬에서 제공되며 요청을 만들지 않으므로 추적되지 않습니다.

개발

git clone git@github.com:growthbook/skills.git ../skills
cp agent-skills.local.json.example agent-skills.local.json  # edit if not at ../skills

npm install
npm run build
npm start

독립형 HTTP 모드

기본적으로 서버는 stdio를 통해 실행됩니다. GB_MCP_TRANSPORT=http을 설정하여 /mcp(스킬 + API 도구) 및 /mcp/api(기능 전용)에서 MCP를 노출하는 독립형 HTTP 서버로 실행하고, OAuth 2.0 보호 리소스 표면(RFC 9728 메타데이터 + RFC 6750 WWW-Authenticate) 뒤에 배치하세요.

• GB_MCP_URL (HTTP 모드에서 필수) — 서버의 공개 기본 URL. OAuth 리소스(대상) 및 보호 리소스 메타데이터에 기록되므로 요청 헤더에서 파생되지 않습니다. 이 값 없이는 서버가 시작을 거부합니다.
• GB_MCP_PORT (기본값 3333) 및 GB_MCP_HOST (기본값 127.0.0.1).
• 수신 베어러는 GrowthBook REST API를 프로브하여 검증됩니다. 거부된 토큰은 HTTP 401 + WWW-Authenticate을 받아 클라이언트가 새로 고칠 수 있습니다.

신뢰할 수 있는 네트워크에서 실행하거나 루프백에 바인딩하세요. 멀티 테넌트 또는 공개 배포의 경우 자체 게이트웨이/인증으로 앞단을 구성하세요.

릴리스

릴리스는 신중하게 진행됩니다: package.json에서 버전을 올리고 npm run sync-version을 실행한 후(manifest.json, server.json 및 .cursor-plugin/plugin.json 업데이트) 일치하는 v* 태그를 푸시하세요:

git tag v2.0.0
git push origin v2.0.0

해당 태그가 지정된 커밋(컷 시점에 스킬 고정)은 다음을 게시합니다:

• @growthbook/mcp을 npm에 — 사전 릴리스(-이 있는 버전, 예: 2.0.0-beta.1)는 beta dist-tag로 이동하고 안정 버전은 latest가 됩니다
• amd64 + arm64 멀티 아키텍처 이미지를 ghcr.io/growthbook/growthbook-mcp에 (:<version>, 안정 릴리스의 경우 :<major>, :<major>.<minor> 및 :latest 추가)
• MCP 레지스트리 항목
• GitHub 릴리스

Cursor 플러그인은 CI에서 게시되지 않습니다: Cursor는 버전 범프가 적용된 후 기본 분기에서 플러그인을 재검토합니다.

npx @growthbook/mcp@<version>으로 릴리스를 설치하거나 ghcr.io/growthbook/growthbook-mcp:<version>을 가져오세요.