Bootpay Admin MCP Server

부트페이 관리자 업무를 자동화하는 MCP(Model Context Protocol) 서버입니다. Claude Desktop, Claude Code 등 MCP 호환 클라이언트에서 자연어로 가맹점 관리, 결제 설정, 키체인 발급 등의 작업을 수행할 수 있습니다.

주요 기능

카테고리	도구	설명
인증	browser_login	브라우저 콜백 기반 로그인 (권장)
	login	이메일/비밀번호 직접 로그인 (원격 서버용)
	logout	세션 종료 및 토큰 삭제
	set_token	JWT 토큰 수동 설정
	get_auth_status	인증 상태 및 현재 프로젝트 확인
프로젝트	browser_select_project	브라우저 UI에서 프로젝트 선택 (권장)
	list_projects	프로젝트 목록 데이터 조회
	switch_project	프로젝트 프로그래밍 방식 전환
	create_project	추가 프로젝트 생성
가맹점	create_seller	가맹점 생성 (기본 프로젝트 자동 생성)
	search_sellers	가맹점 검색 (provider_id 기반)
	get_seller	가맹점 상세 정보 조회
	update_seller	가맹점 정보 수정
결제 설정	get_payment_settings	PG사별 결제수단 및 활성화 상태 조회
	activate_payment_method	결제수단 활성화/비활성화
	set_sandbox_mode	샌드박스(테스트) 모드 설정
	set_payment_mode	결제 모드 변경
	update_payment_resource	PG 인증정보(site_cd, site_key 등) 설정
키체인	list_keychains	커머스용 키체인 목록 조회
	list_api_scopes	API 스코프(권한) 목록 조회
	create_keychain	clientKey 발급 (커머스용/결제용 선택)
	delete_keychain	키체인 비활성화(revoke)
위젯	list_widgets	결제 위젯 목록 조회
	get_widget	위젯 상세 조회
	create_widget	결제 위젯 생성
	configure_widget	위젯 스타일(테마/컬러/레이아웃) 설정
	update_widget	위젯 결제수단/설정 업데이트
	delete_widget	위젯 삭제
	get_widget_default_styles	위젯 타입별 기본 스타일 조회
상품	list_products	상품 목록 조회 (페이지네이션/검색)
	get_product	상품 상세 조회
	create_product	상품 등록
	update_product	상품 수정
	delete_product	상품 삭제

빠른 시작

사전 요구사항

• Node.js 18+
• 부트페이 관리자 계정

설치

npm (권장)

npm install -g @bootpay/bootpay-admin-mcp

Git (tarball)

npm install -g https://github.com/bootpay/bootpay-admin-mcp/archive/main.tar.gz

Git (clone)

git clone https://github.com/bootpay/bootpay-admin-mcp.git
cd bootpay-admin-mcp
npm install
npm run build

Claude Desktop 설정

claude_desktop_config.json에 아래 내용을 추가합니다.

npm 설치 시:

{
  "mcpServers": {
    "bootpay-admin": {
      "command": "npx",
      "args": ["@bootpay/bootpay-admin-mcp"]
    }
  }
}

Git 설치 시:

{
  "mcpServers": {
    "bootpay-admin": {
      "command": "node",
      "args": ["/path/to/bootpay-admin-mcp/dist/index.js"]
    }
  }
}

Claude Code 설정

.mcp.json 파일에 추가합니다.

npm 설치 시:

{
  "mcpServers": {
    "bootpay-admin": {
      "command": "npx",
      "args": ["@bootpay/bootpay-admin-mcp"]
    }
  }
}

Git 설치 시:

{
  "mcpServers": {
    "bootpay-admin": {
      "command": "node",
      "args": ["/path/to/bootpay-admin-mcp/dist/index.js"]
    }
  }
}

워크플로우

1단계: 로그인

browser_login → 브라우저가 열리고 로그인 완료 시 토큰 자동 전달

원격 서버에서는 callback_url 파라미터를 지정하거나 login 도구를 사용합니다.

2단계: 프로젝트 선택

browser_select_project → 브라우저에서 프로젝트 선택 UI 표시

새 가맹점이 필요한 경우:

create_seller → 가맹점 + 기본 프로젝트 자동 생성 및 전환

3단계: 업무 수행

프로젝트 선택 후 각 도구를 사용하여 업무를 수행합니다.

결제 설정 예시:

get_payment_settings → activate_payment_method(kcp, card) → set_sandbox_mode(kcp, card)

키체인 발급 예시:

# 커머스용 clientKey
create_keychain(name: "개발용", targets: ["internal"])

# 결제용 clientKey
create_keychain(name: "결제 테스트", targets: ["core"])

# 둘 다 동시 발급
create_keychain(name: "풀스택 개발용", targets: ["internal", "core"])

clientKey 종류

종류	targets 값	API 서버	용도
커머스용	["internal"]	internal-api (ProjectKeyChain)	주문, 상품, 재고 등 커머스 API
결제용	["core"]	core-api (AppKeyChain)	결제 요청, 조회, 취소 등 결제 API

MCP Resources

리소스	URI	설명
session	bootpay://session	현재 세션 상태 (인증, 환경, 프로젝트)
workflow-guide	bootpay://workflow-guide	전체 워크플로우 가이드

프로젝트 구조

mcp/
├── src/
│   ├── index.ts              # 서버 엔트리포인트
│   ├── auth/
│   │   ├── callback-server.ts   # 브라우저 로그인 콜백 서버
│   │   ├── project-select-server.ts  # 프로젝트 선택 UI 서버
│   │   └── token-manager.ts     # JWT 토큰 관리
│   ├── client/
│   │   ├── core-api.ts          # Core API 클라이언트 (결제)
│   │   └── internal-api.ts      # Internal API 클라이언트 (커머스)
│   ├── config/
│   │   └── environment.ts       # 환경 설정
│   ├── errors/
│   │   └── index.ts             # 에러 포맷팅
│   ├── resources/
│   │   └── index.ts             # MCP Resources (session, workflow-guide)
│   └── tools/
│       ├── index.ts             # 도구 등록 진입점
│       ├── auth.ts              # 인증 도구
│       ├── seller.ts            # 가맹점 관리 도구
│       ├── project.ts           # 프로젝트 관리 도구
│       ├── keychain.ts          # 키체인(API키) 관리 도구
│       ├── payment.ts           # 결제 설정 도구
│       ├── widget.ts            # 결제 위젯 도구
│       └── product.ts           # 상품 관리 도구
├── tests/
│   ├── tools/                   # 도구 단위 테스트
│   └── integration/             # 통합 테스트
├── package.json
├── tsconfig.json
└── vitest.config.ts

개발

# 개발 모드 (tsx 사용)
npm run dev

# 타입 체크
npm run typecheck

# 테스트
npm test

# 테스트 (watch 모드)
npm run test:watch

# 빌드
npm run build

기술 스택

• Runtime: Node.js (ES2022)
• Language: TypeScript (strict mode)
• MCP SDK: @modelcontextprotocol/sdk ^1.12.1
• Validation: Zod ^3.24.4
• Test: Vitest ^4.1.0
• Transport: Stdio (표준 입출력)