PortOne MCP Server

포트원 사용자를 위한 MCP (Model Context Protocol) 서버입니다. 포트원 개발자센터, 헬프센터 등 공식 문서 내용을 LLM(Large Language Model)에 제공해 정확한 정보를 바탕으로 사용자의 연동 및 질의를 돕도록 합니다.

이외에도 포트원 콘솔에서 제공하는 기능 중 일부를 수행할 수 있습니다.

• 채널 목록 조회
• 테스트 채널 추가
• 하위 상점 조회
• 결제 내역 조회
• 거래대사 건별 내역 조회 (정산/거래 대사, 불일치 상세 포함)
• 거래대사 정산 요약 조회
• 거래대사 정산 통계 조회

콘솔 기능 사용 시 브라우저를 통해 콘솔 로그인이 필요합니다.

DXT를 이용한 설치

DXT (Desktop Extensions)를 이용해 MCP 서버를 원클릭으로 설치할 수 있습니다.

1. GitHub Releases에서 최신 portone-mcp-server.dxt 파일을 다운로드합니다.

2. 지원하는 AI 도구(Claude Desktop 등)에서 다운로드한 .dxt 파일을 드래그 앤 드롭하거나 열기를 통해 설치합니다.

3. 설치 후 도구를 재시작하여 MCP 서버가 정상적으로 등록되었는지 확인합니다.

MCP 서버 등록하기

1. Node.js 22.6.0 이상이 설치되어 있어야 합니다.

2. 사용하는 AI 도구의 MCP 설정에서 아래 내용을 추가합니다. (Cursor, Windsurf, Claude Desktop, etc...)

   "mcpServers": {
   
     // 기존 설정
   
     "portone-mcp-server": {
       "command": "npx",
       "args": [
         "-y",
         "@portone/mcp-server@latest"
       ]
     }
   }
   

3. 도구를 재시작해 portone-mcp-server 및 해당 서버가 제공하는 도구들이 잘 등록되었는지 확인합니다.

서버 환경에서 사용하기 (액세스 토큰 주입)

브라우저 로그인이 불가능한 서버 환경에서는 PORTONE_ACCESS_TOKEN 환경 변수로 외부에서 발급한 콘솔 OAuth 액세스 토큰을 주입할 수 있습니다. 이 변수가 설정되면 브라우저를 통한 대화형 OAuth 로그인 플로우(로컬 콜백 서버, PKCE)를 건너뛰고, 주입된 토큰을 그대로 콘솔 기능 호출의 Authorization 헤더로 사용합니다.

"mcpServers": {
  "portone-mcp-server": {
    "command": "npx",
    "args": ["-y", "@portone/mcp-server@latest"],
    "env": {
      "PORTONE_ACCESS_TOKEN": "<콘솔에서 발급한 액세스 토큰>"
    }
  }
}

• PORTONE_ACCESS_TOKEN: 콘솔 OAuth 액세스 토큰(필수). 설정 시 정적 토큰 모드로 동작합니다.
• PORTONE_TOKEN_TYPE: 토큰 타입(선택, 기본값 Bearer).

엔드포인트 오버라이드

기본적으로 MCP 서버는 PortOne 운영(prod) 환경에 연결됩니다. 아래 환경 변수를 설정하면 각 서비스 엔드포인트를 개별적으로 다른 환경(예: 내부 테스트 환경)으로 오버라이드할 수 있습니다. 설정하지 않은 항목은 운영 환경 기본값을 사용합니다.

• PORTONE_CONSOLE_URL: 콘솔 (OAuth 브라우저 로그인)
• PORTONE_MERCHANT_SERVICE_URL: 머천트 서비스 (OAuth 토큰 교환·갱신)
• PORTONE_CHANNEL_SERVICE_URL: 채널 서비스 (채널 조회·추가)
• PORTONE_GRAPHQL_URL: GraphQL 게이트웨이 (스토어·결제·거래대사·정산)

"mcpServers": {
  "portone-mcp-server": {
    "command": "npx",
    "args": ["-y", "@portone/mcp-server@latest"],
    "env": {
      "PORTONE_CONSOLE_URL": "<대상 환경 콘솔 URL>",
      "PORTONE_GRAPHQL_URL": "<대상 환경 GraphQL URL>"
    }
  }
}

개발하기

요구사항

• Node.js 22.6.0 이상
• pnpm (권장) 또는 npm

1. 저장소를 클론한 후 필요한 패키지 설치하기

   pnpm install
   

2. MCP 서버 실행 (개발 모드)

   pnpm dev
   

3. 코드 린팅 및 포맷팅

   pnpm lint
   pnpm format
   

4. 타입 체크

   pnpm typecheck
   

5. 빌드 및 퍼블리싱

   # 먼저 package.json의 version을 변경합니다.
   rm -rf dist
   pnpm install
   pnpm build
   pnpm publish
   

6. 로컬 환경의 MCP 서버 등록하기

   "mcpServers": {
      "portone-mcp-server": {
        "command": "node",
        "args": [
          "/your/absolute/path/to/portone-mcp-server/dist/index.js"
        ]
      }
   }
   

7. 문서 업데이트하기

   요구사항:

   • 로컬에 developers.portone.io, help.portone.io 저장소가 클론되어 있어야 합니다.
   • nvm (Node Version Manager) 및 노드 20, 23 버전이 설치되어 있어야 합니다.
   • corepack이 설치되어 있어야 합니다.

   developers.portone.io 저장소에서 생성된 문서를 MCP 서버에 업데이트하려면 다음과 같이 실행합니다:

   # 환경 변수를 사용하는 방법
   export DEVELOPERS_PORTONE_IO_PATH="/path/to/developers.portone.io"
   export HELP_PORTONE_IO_PATH="/path/to/help.portone.io"
   pnpm update-docs
   
   # 또는 대화형으로 실행
   pnpm update-docs
   # 프롬프트가 표시되면 developers.portone.io, help.portone.io 저장소 경로 입력
   

   이 스크립트는 다음을 수행합니다:

   1. developers.portone.io, help.portone.io 저장소에서 pnpm docs-for-llms 명령을 실행 (로컬에 설정된 브랜치 기준으로 문서 생성)
   2. MCP 서버의 docs 디렉토리를 새로 생성된 내용으로 교체
   3. 개발자센터, 헬프센터 외 일부 문서 다운로드 및 교체

Python 버전에서 마이그레이션

기존에 Python 버전(<0.13.0)의 MCP 서버를 사용하고 계셨다면 TypeScript 버전으로 마이그레이션하는 것을 권장합니다.

마이그레이션 방법

1. MCP 설정 변경

   기존 파이썬 버전 설정:

   "mcpServers": {
     "portone-mcp-server": {
       "command": "uvx",
       "args": ["portone-mcp-server@latest"]
     }
   }
   

   새로운 TypeScript 버전 설정:

   "mcpServers": {
     "portone-mcp-server": {
       "command": "npx",
       "args": ["-y", "@portone/mcp-server@latest"]
     }
   }
   

2. 환경 변수 및 API 시크릿 설정은 동일하게 유지됩니다.

3. Node.js 설치: Node.js 22.6.0 이상이 필요합니다.

4. AI 도구 재시작: 설정 변경 후 사용 중인 AI 도구를 재시작합니다.

라이선스

Apache License 2.0 OR MIT License