portone-io/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 사용" 옵션을 비활성화한 후 재시작하면 정상적으로 작동합니다.
## MCP 서버 등록하기
1. Node.js 22.6.0 이상이 설치되어 있어야 합니다.
1. 사용하는 AI 도구의 MCP 설정에서 아래 내용을 추가합니다. (Cursor, Windsurf, Claude Desktop, etc...)
json
"mcpServers": {
// 기존 설정
"portone-mcp-server": {
"command": "npx",
"args": [
"-y",
"@portone/mcp-server@latest"
1. 도구를 재시작해 portone-mcp-server 및 해당 서버가 제공하는 도구들이 잘 등록되었는지 확인합니다.
> [!CAUTION]
> 제3자 AI 서비스를 사용할 경우, API 응답(조회된 데이터 등)이 AI 서비스 측으로 전달되어 저장되거나 해당 서비스의 정책에 따라 모델 학습에 사용될 수 있습니다.
> MCP 서버는 API 응답에 포함된 개인정보가 외부로 전달되지 않도록, 우선적으로 해당 정보를 식별 및 제거하는 보호 조치를 마련하고 있습니다.
> 다만, 그 외의 정보는 AI 서비스의 운영 정책에 따라 일시적으로 저장되거나 처리될 수 있는 점을 유의해야 합니다.
## 서버 환경에서 사용하기 (액세스 토큰 주입)
브라우저 로그인이 불가능한 서버 환경에서는 PORTONEACCESSTOKEN 환경 변수로
외부에서 발급한 콘솔 OAuth 액세스 토큰을 주입할 수 있습니다. 이 변수가 설정되면
브라우저를 통한 대화형 OAuth 로그인 플로우(로컬 콜백 서버, PKCE)를 건너뛰고,
주입된 토큰을 그대로 콘솔 기능 호출의 Authorization 헤더로 사용합니다.
json
"mcpServers": {
"portone-mcp-server": {
"command": "npx",
"args": ["-y", "@portone/mcp-server@latest"],
"env": {
"PORTONEACCESSTOKEN": " "
PORTONEACCESSTOKEN: 콘솔 OAuth 액세스 토큰(필수). 설정 시 정적 토큰 모드로 동작합니다.
PORTONETOKENTYPE: 토큰 타입(선택, 기본값 Bearer).
> [!IMPORTANT]
> - 정적 토큰 모드에서는 리프레시 토큰이 없으므로 토큰의 발급/갱신/만료 관리는
> 호출 측(서버)의 책임입니다. 만료된 토큰을 주입하면 콘솔 기능 호출이 실패합니다.
> - 토큰은 프로세스별로 격리됩니다. 여러 사용자를 처리하는 서버라면 사용자마다
> 별도의 프로세스에 해당 사용자의 토큰을 주입해, 토큰이 공유되지 않도록 하세요.
> - PORTONEACCESSTOKEN 이 없으면 기존과 동일하게 브라우저 로그인 플로우로 동작합니다.
## 엔드포인트 오버라이드
기본적으로 MCP 서버는 PortOne 운영(prod) 환경에 연결됩니다. 아래 환경 변수를
설정하면 각 서비스 엔드포인트를 개별적으로 다른 환경(예: 내부 테스트 환경)으로
오버라이드할 수 있습니다. 설정하지 않은 항목은 운영 환경 기본값을 사용합니다.
PORTONECONSOLEURL: 콘솔 (OAuth 브라우저 로그인)
PORTONEMERCHANTSERVICEURL: 머천트 서비스 (OAuth 토큰 교환·갱신)
PORTONECHANNELSERVICEURL: 채널 서비스 (채널 조회·추가)
PORTONEGRAPHQLURL: GraphQL 게이트웨이 (스토어·결제·거래대사·정산)
json
"mcpServers": {
"portone-mcp-server": {
"command": "npx",
"args": ["-y", "@portone/mcp-server@latest"],
"env": {
"PORTONECONSOLEURL": " ",
"PORTONEGRAPHQLURL": " "
> [!NOTE]
> - 오버라이드는 콘솔 기능(스토어·채널·결제·거래대사·정산 등) 호출 대상만
> 바꿉니다. 문서/헬프센터 조회는 환경과 무관하게 동일하게 동작합니다.
> - 브라우저 로그인 대신 PORTONEACCESSTOKEN 을 함께 사용하는 경우, 오버라이드한
> 환경에서 발급한 토큰을 주입해야 합니다.
## 개발하기
### 요구사항
Node.js 22.6.0 이상
pnpm (권장) 또는 npm
1. 저장소를 클론한 후 필요한 패키지 설치하기
bash
pnpm install
1. MCP 서버 실행 (개발 모드)
bash
pnpm dev
1. 코드 린팅 및 포맷팅
bash
pnpm lint
pnpm format
1. 타입 체크