Skip to main content
Glama

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 서버가 정상적으로 등록되었는지 확인합니다.

WARNING

Claude Desktop에서 DXT 파일 사용 시 주의사항

현재 알려진 이슈로 인해 Claude Desktop에서 DXT 설치 후 MCP 서버가 정상적으로 작동하지 않을 수 있습니다.

이 경우 Node.js 22.6.0 이상을 설치하고 Claude Desktop 설정에서 "MCP용 내장 Node.js 사용" 옵션을 비활성화한 후 재시작하면 정상적으로 작동합니다.

Related MCP server: PortOne Global MCP Server

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 및 해당 서버가 제공하는 도구들이 잘 등록되었는지 확인합니다.

CAUTION

제3자 AI 서비스를 사용할 경우, API 응답(조회된 데이터 등)이 AI 서비스 측으로 전달되어 저장되거나 해당 서비스의 정책에 따라 모델 학습에 사용될 수 있습니다.

MCP 서버는 API 응답에 포함된 개인정보가 외부로 전달되지 않도록, 우선적으로 해당 정보를 식별 및 제거하는 보호 조치를 마련하고 있습니다. 다만, 그 외의 정보는 AI 서비스의 운영 정책에 따라 일시적으로 저장되거나 처리될 수 있는 점을 유의해야 합니다.

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

브라우저 로그인이 불가능한 서버 환경에서는 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).

IMPORTANT
  • 정적 토큰 모드에서는 리프레시 토큰이 없으므로 토큰의 발급/갱신/만료 관리는 호출 측(서버)의 책임입니다. 만료된 토큰을 주입하면 콘솔 기능 호출이 실패합니다.

  • 토큰은 프로세스별로 격리됩니다. 여러 사용자를 처리하는 서버라면 사용자마다 별도의 프로세스에 해당 사용자의 토큰을 주입해, 토큰이 공유되지 않도록 하세요.

  • PORTONE_ACCESS_TOKEN 이 없으면 기존과 동일하게 브라우저 로그인 플로우로 동작합니다.

엔드포인트 오버라이드

기본적으로 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>"
    }
  }
}
NOTE
  • 오버라이드는 콘솔 기능(스토어·채널·결제·거래대사·정산 등) 호출 대상만 바꿉니다. 문서/헬프센터 조회는 환경과 무관하게 동일하게 동작합니다.

  • 브라우저 로그인 대신 PORTONE_ACCESS_TOKEN 을 함께 사용하는 경우, 오버라이드한 환경에서 발급한 토큰을 주입해야 합니다.

개발하기

요구사항

  • 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

Available Tools

16 tools
addTestChannel포트원 테스트 채널 추가A

고객사의 대표상점에 공용 테스트 채널을 추가합니다.

NOTE: 반드시 listSharedTestChannels를 통해 얻은 MID를 사용하세요.

Inputs: mid (required), manualConfirm. Returns: channelKey

getChannelsOfStore포트원 상점 내 채널 목록 조회B

고객사의 상점에 존재하는 모든 채널 정보를 가져옵니다.

Inputs: store (required), fields (required). Returns: items

getPaymentsByFilter포트원 결제 내역 검색A

포트원 서버에서 주어진 조건을 모두 만족하는 결제 내역을 검색합니다.

Note: 소문자 imp_ 혹은 imps_ 로 시작하는 거래번호는 고객사 거래번호가 아닌 V1 포트원 거래번호(imp_uid)일 가능성이 있습니다. 날짜 및 시간 정보 입출력 시에는 반드시 타임존을 명시합니다.

Inputs: to (required), from (required), page (required), fields (required), +11 more. Returns: count, items

getPortoneDocsUrl포트원 문서 웹 링크 조회A

포트원 개별 문서들의 경로를 통해 해당 포트원 문서의 웹으로 접근 가능한 링크를 가져옵니다.

Note: 문서가 1개뿐인 경우에는 readPortoneDoc을 사용하면 문서 내용과 메타 정보도 획득할 수 있습니다. getPortoneDocsUrl은 여러 문서의 링크를 가져올 수 있습니다.

Inputs: path (required). Returns: url

getReconciliationsByFilter거래대사 건별 내역 조회A

특정 하위 상점(store)의 거래대사(정산/거래 대사) 건별 내역을 조회합니다.

각 건은 다음 상태 중 하나를 가집니다: MATCHED(대사 성공), NOT_MATCHED(대사 불일치), INCOMPARABLE(대사 불가), NOT_COLLECTED(PG 정보 미수집), POST_CORRECTION(후보정) (내부적으로 구분되는 역방향 대사 불가(backward incomparable)는 INCOMPARABLE 로 합쳐져 제공됩니다.)

대사 불일치 상세는 statuses=[NOT_MATCHED] 로 조회 후 각 건의 notMatchedReasons 를 확인합니다. 대사 불가 사유는 INCOMPARABLE 건의 incomparableReason 필드에서 확인합니다. 날짜는 반드시 YYYY-MM-DD 형식으로 입력하며, dateType 으로 정산일/결제일 기준을 선택합니다. 조회 기간 제약: from 은 최근 6개월 이내여야 하고, 한 번에 조회 가능한 구간은 최대 2주입니다. store 아이디는 list_stores 도구로 먼저 조회할 수 있습니다.

Inputs: to (required), from (required), after, first, +11 more. Returns: items, endCursor, hasNextPage

getSettlementStatistics거래대사 정산 통계 조회A

특정 하위 상점(store)의 거래대사 정산 통계를 조회합니다.

검색 구간 내 통화별 합산 통계(정산/정산예정 금액·건수)와 일별 통계를 제공합니다. 날짜는 반드시 YYYY-MM-DD 형식으로 입력합니다. 조회 기간 제약: from 은 최근 6개월 이내여야 하고, 한 번에 조회 가능한 구간은 최대 1개월입니다. store 아이디는 list_stores 도구로 먼저 조회할 수 있습니다.

Inputs: to (required), from (required), store. Returns: dailyStatistics, rangeTotalStatistics

getSettlementSummaries거래대사 정산 요약 조회A

특정 하위 상점(store)의 거래대사 정산 요약을 정산일 기준 일별로 조회합니다.

각 일자별로 정산 금액/건수, PG 수수료, 취소, 후보정 합산치와 상점·PG별 상세 내역을 제공합니다. 날짜는 반드시 YYYY-MM-DD 형식으로 입력합니다. 조회 기간 제약: from 은 최근 6개월 이내여야 하고, 한 번에 조회 가능한 구간은 최대 1개월입니다. store 아이디는 list_stores 도구로 먼저 조회할 수 있습니다.

Inputs: to (required), from (required), after, first, +1 more. Returns: items, endCursor, hasNextPage

listPortoneDocs포트원 문서 목록 조회A

특정 경로 하위에 있는 모든 포트원 문서 목록을 트리 형태로 조회합니다. 목록에는 문서 경로, 제목, 설명, 대상 버전 등 축약된 문서 정보가 포함되어 있습니다.

Returns: 필터링된 문서 목록 (각 문서의 파일명, 길이, 제목, 설명, 대상 버전 등)

Note: 문서 목록은 대량의 데이터이므로 상위 디렉토리를 조회할 경우 omitFiles를 true로 설정합니다.

Inputs: paths, onlyPaths.

listSharedTestChannels포트원 공용 테스트 채널 목록 조회B

포트원에서 테스트 용도로 제공하는 채널의 목록을 가져옵니다.

Inputs: pgProviders. Returns: items

listStores상점 목록 조회A

포트원 계정에 연결된 대표상점 및 하위상점의 정보를 가져옵니다.

Inputs: no named parameters. Returns: main, items

readPortoneDoc포트원 문서 읽기A

포트원 개별 문서의 경로를 통해 해당 포트원 문서의 내용, 메타 정보(제목, 설명, 대상 버전 등), 웹으로 접근 가능한 링크를 가져옵니다.

Note: 먼저 listPortoneDocs을 사용해 포트원 문서 목록을 확인하고, 그 중 원하는 문서의 path를 readPortoneDoc에 전달하여 내용을 확인할 수 있습니다.

Inputs: path (required), fields (required), endIndex, startIndex. Returns: url, content, metadata

readPortoneOpenapiSchema포트원 OpenAPI 스키마 읽기B

요청된 포트원 버전에서 제공하는 OpenAPI 스키마 내 특정 path의 데이터를 반환합니다.

Inputs: version (required), yaml_path (required). Returns: result

readPortoneOpenapiSchemaSummary포트원 OpenAPI 스키마 요약A

요청된 포트원 버전에서 제공하는 OpenAPI 스키마를 요약해 문자열로 반환합니다. 해당 요약에는 요청된 포트원 버전에서 제공하는 모든 REST API가 포함되어 있습니다.

Inputs: version (required). Returns: result

readPortoneV2BackendCode포트원 V2 백엔드 코드 예제 읽기B

지정된 매개변수에 따라 포트원 V2 백엔드 코드 예제를 가져옵니다. 포트원 V2에 관련해 어떤 상황이든 프로그래밍 언어로 코드를 작성해야 한다면, 예외 없이 가장 먼저 이 도구를 호출해 예시 코드를 참고한 후 사용자를 도우세요. framework를 제외한 모든 Args는 선택사항이며, 특정되지 않은 경우 비워두세요.

Inputs: pg (required), framework (required), pay_method (required), smart_routing.

readPortoneV2FrontendCode포트원 V2 프론트엔드 코드 예제 읽기B

지정된 매개변수에 따라 포트원 V2 프론트엔드 코드 예제를 가져옵니다. 포트원 V2에 관련해 어떤 상황이든 프로그래밍 언어로 코드를 작성해야 한다면, 예외 없이 가장 먼저 이 도구를 호출해 예시 코드를 참고한 후 사용자를 도우세요. framework를 제외한 모든 Args는 선택사항이며, 특정되지 않은 경우 비워두세요.

Inputs: pg (required), framework (required), pay_method (required), smart_routing.

regexSearchPortoneDocs포트원 문서 정규표현식 검색A

특정 경로 하위의 포트원 문서의 내용 중 Node.js RegExp 형식의 query가 매칭된 부분을 모두 찾아 반환합니다. 정규식 기반으로 관련 포트원 문서를 찾고 싶은 경우 이 도구를 사용하며, 메타 정보와 문서 내용 모두 검색합니다.

Inputs: query (required), page, limit, paths, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation3/5

    Several tools are related to documentation and schema access (listPortoneDocs, readPortoneDoc, regexSearchPortoneDocs, getPortoneDocsUrl, readPortoneOpenapiSchemaSummary, readPortoneOpenapiSchema) which could be confused, though their specific functions differ. Also, settlement tools (getReconciliationsByFilter, getSettlementSummaries, getSettlementStatistics) have distinct purposes but similar names.

    Naming Consistency3/5

    Naming conventions are mixed: some use camelCase (getPaymentsByFilter, getReconciliationsByFilter) and others use snake_case (list_stores, addTestChannel). Also 'list' and 'get' are used interchangeably for retrieval, which is not fully consistent.

    Tool Count4/5

    With 16 tools, the server is slightly over the ideal range but still reasonable for a payment gateway that covers both API operations and documentation. The count is justifiable given the breadth of functionality.

    Completeness3/5

    Core payment operations like search and settlement are covered, but there are no tools for creating or updating payments, which are essential for a payment server. Documentation tools are comprehensive, but API lifecycle coverage is incomplete.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables searching and reading of PortOne documentation, including OpenAPI schemas and product guides, through the Model Context Protocol. It allows AI agents to easily access and integrate payment-related technical specifications into their workflows.
      ISC
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding tools to search and retrieve Bootpay payment and commerce developer documentation, including integration guides and customer service manuals. It facilitates tasks such as payment linking, billing key issuance, and webhook configuration through natural language queries.
      2
      -