korea-payments-mcp

MCP (Model Context Protocol) server for Korean payment gateways.

v0.2 scope: PortOne V2 + TossPayments (결제 조회 / 취소, PortOne 웹훅 검증) Planned: KakaoPay, 국세청 사업자번호 조회, 현금영수증

Why

영어권 MCP 생태계에 한국 결제 도메인 커버리지가 사실상 없다. Claude/Cursor 등에서 결제 이슈를 디버깅할 때 PortOne 대시보드를 열지 않고도 조회·부분환불·웹훅 서명 검증을 툴 콜로 처리하기 위함.

Tools

각 툴은 관련 환경변수가 설정된 경우에만 노출된다 (컨텍스트 절약 + 실수 방지).

Tool	필요 env	Description
portone_get_payment	PORTONE_API_SECRET	PortOne V2 결제 단건 조회 (GET /payments/{id})
portone_cancel_payment	PORTONE_API_SECRET	PortOne V2 결제 취소/환불 (전액/부분, 낙관적 락 지원)
portone_verify_webhook	PORTONE_WEBHOOK_SECRET	PortOne V2 웹훅 서명 검증 (Standard Webhooks 스펙, HMAC-SHA256)
toss_get_payment	TOSS_SECRET_KEY	TossPayments 결제 조회 (paymentKey 또는 orderId)
toss_cancel_payment	TOSS_SECRET_KEY	TossPayments 결제 취소/환불 (전액/부분)

PortOne 공식 문서 확인: V2 웹훅은 Standard Webhooks 스펙을 준수하며, webhook-id / webhook-timestamp / webhook-signature 헤더와 {id}.{ts}.{body} 형식의 signed payload를 사용한다. 공식 @portone/server-sdk를 쓰는 것도 가능하지만, 본 MCP는 Toss/Kakao 등 다른 Standard Webhooks 준수 게이트웨이에도 재사용하기 위해 스펙을 직접 구현했다.

Setup

npm install
cp .env.example .env
# .env 에 PORTONE_API_SECRET, PORTONE_WEBHOOK_SECRET 입력
npm run build

Claude Desktop / Claude Code 등록

~/Library/Application Support/Claude/claude_desktop_config.json 또는 각 MCP 클라이언트 설정:

{
  "mcpServers": {
    "korea-payments": {
      "command": "node",
      "args": ["/absolute/path/to/korea-payments-mcp/dist/index.js"],
      "env": {
        "PORTONE_API_SECRET": "your-portone-v2-api-secret",
        "PORTONE_WEBHOOK_SECRET": "whsec_...",
        "TOSS_SECRET_KEY": "test_sk_..."
      }
    }
  }
}

Development

npm run dev        # tsx watch
npm run typecheck
npm test           # node:test + tsx (Standard Webhooks 공식 vector 포함)
npm run inspect    # MCP Inspector GUI (브라우저에서 tools/list, tools/call 검증)

Stdio 스모크 (CI용)

scripts/smoke.mjs가 MCP 프로토콜 초기화 + tools/list 응답을 검증. 플래그로 어떤 env var를 설정할지 지정하고, 예상되는 툴 이름 집합과 대조:

npm run build
node scripts/smoke.mjs                              # portone only (2 tools)
node scripts/smoke.mjs --with-webhook               # portone + webhook (3)
node scripts/smoke.mjs --with-webhook --with-toss   # portone + webhook + toss (5)
node scripts/smoke.mjs --no-portone --with-toss     # toss only (2)

CI(GitHub Actions)에서 이 4가지 조합을 매 커밋 검증한다.

Roadmap

• [x] PortOne V2 조회/취소 + 웹훅 검증 (v0.1)
• [x] TossPayments 조회/취소 (v0.2)
• [ ] TossPayments 웹훅 검증
• [ ] TossPayments 빌링키 (정기결제)
• [ ] KakaoPay (일회성/정기결제)
• [ ] 국세청 사업자번호 진위확인 (공공데이터포털)
• [ ] 현금영수증 발급 (PortOne 우선)
• [ ] Read-only search_payments (기간/상태 필터)

License

MIT