GrowthBook

GrowthBook MCP Thin

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

도구	용도
growthbook_list_skills	번들로 포함된 GrowthBook 에이전트 스킬 목록 표시 (이름 + 설명)
growthbook_read_skill	전체 스킬 마크다운 반환 (워크플로 + 가드레일)
growthbook_api_read	GrowthBook API에 대한 인증된 GET 패스스루
growthbook_api_write	인증된 POST/PUT/PATCH/DELETE 패스스루

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

클라이언트에 여러 MCP 서버가 로드되어 있을 때 모호함을 피하기 위해 도구 이름에는 growthbook_ 접두사가 붙습니다.

설치 / 실행

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_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 인증 서버를 알립니다.

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를 설정하세요:

"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 체크아웃의 모든 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가 아닌 경우, 인증 실패, 자체 호스팅 404 힌트, 속도 제한을 포함한 실행 가능한 오류(isError: true) 반환
• 자유 형식 경로는 GrowthBook REST API를 대상으로 함

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 서버로 실행되어 OAuth 2.0 보호 리소스 표면(RFC 9728 메타데이터 + RFC 6750 WWW-Authenticate) 뒤에서 /mcp (스킬 + API 도구) 및 /mcp/api (기능 전용)에서 MCP를 노출합니다.

• 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 에서 버전을 올린 다음 일치하는 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 릴리스

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