PortOne MCP Server

PortOne MCP 服务

这是面向 PortOne 用户的 MCP（Model Context Protocol）服务。它将 PortOne 开发者中心、帮助中心等官方文档内容提供给 LLM（Large Language Model），帮助用户基于准确信息进行集成和查询。

此外，还可以执行 PortOne 控制台提供的部分功能。

• 查询渠道列表
• 添加测试渠道
• 查询子商户
• 查询支付记录
• 查询逐笔交易对账明细（包括结算/交易对账及差异详情）
• 查询交易对账结算摘要
• 查询交易对账结算统计信息

使用控制台功能时，需要通过浏览器登录控制台。

使用 DXT 安装

可以使用 DXT（Desktop Extensions） 一键安装 MCP 服务。

1. 从 GitHub Releases 下载最新的 portone-mcp-server.dxt 文件。

2. 在受支持的 AI 工具（如 Claude Desktop）中，将下载的 .dxt 文件拖放到窗口中，或通过打开文件进行安装。

3. 安装后重启工具，并确认 MCP 服务已成功注册。

警告

在 Claude Desktop 中使用 DXT 文件时的注意事项

由于目前存在已知问题，在 Claude Desktop 中安装 DXT 后，MCP 服务可能无法正常运行。

此时，安装 Node.js 22.6.0 或更高版本，在 Claude Desktop 设置中停用 “为 MCP 使用内置 Node.js” 选项，然后重启，即可正常运行。

注册 MCP 服务

1. 需要安装 Node.js 22.6.0 或更高版本。

2. 在所用 AI 工具的 MCP 设置中添加以下内容。（Cursor、Windsurf、Claude Desktop 等）

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

3. 重启工具，确认 portone-mcp-server 及其提供的工具已成功注册。

注意

使用第三方 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）。

重要

• 静态令牌模式下没有刷新令牌，因此令牌的签发、续期和过期管理 由调用方（服务器）负责。注入过期令牌会导致控制台功能调用失败。
• 令牌按进程隔离。如果服务器需要处理多位用户，请为每位用户在 单独的进程中注入该用户的令牌，以避免共享令牌。
• 如果未设置 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>"
    }
  }
}

说明

• 覆盖设置只会更改控制台功能（商店、渠道、支付、交易对账、结算等）的 调用目标。文档/帮助中心查询不受环境影响，行为保持不变。
• 如果同时使用 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）以及 Node.js 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 设置

   现有的 Python 版本设置：

   "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