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 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