Omise Model Context Protocol (MCP)

AIエージェントがOmise MCPサーバーを使用してOmise APIと連携できるようにします。

Omise Model Context Protocol (MCP) サーバーは、AIエージェントが決済処理、顧客管理、財務業務のためにOmise APIと連携するための一連のツールを提供します。

CursorなどのAI搭載コードエディタやClaude Desktopなどの汎用ツールを使用している場合、当社のMCPサーバーをご利用いただけます。

前提条件

Omise MCPサーバーをインストールする前に、以下の前提条件がインストールされていることを確認してください。

必要なソフトウェア

Node.js 20+: JavaScript実行環境(npmパッケージマネージャーを含む)

注: TypeScriptおよびその他の依存関係は、omise-mcpディレクトリでnpm installを実行すると自動的にインストールされます。

インストール手順

macOS

# Homebrewを使用してNode.jsをインストール
brew install node@20

# インストールの確認
node --version
npm --version

Ubuntu/Debian

# パッケージインデックスの更新
sudo apt update

# Node.js 20.xのインストール
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# インストールの確認
node --version
npm --version

Omise APIキー

OmiseアカウントとAPIキーが必要です:

1. Omiseダッシュボードにアクセス
2. アカウントを作成またはログイン
3. 設定 → キーに移動
4. APIキーを取得:
   • テスト環境: pkey_test_およびskey_test_で始まるキーを使用
   • 本番環境: pkey_live_およびskey_live_で始まるキーを使用

重要: 開発中は常にテストキーを使用し、本番環境でのみライブキーを使用してください。

ローカルサーバー

お好みの開発環境のセットアップ手順に従って、ローカルOmise MCPサーバーを実行します。

Claude

Claude DesktopでOmise MCPをセットアップするには:

1. GitHubからomise-mcpをダウンロード
2. コマンドプロンプトでomise-mcpディレクトリに移動し、npm installを実行してすべての依存関係をインストールします。
3. Claude Desktopをダウンロードしてインストール
4. Claude Desktopを開き、設定に移動します。開発者をクリックし、次に設定を編集をクリックします。
   
5. claude_desktop_config.jsonファイルを編集します。内容は以下のようになります:

   {
     "mcpServers": {
       "omise-mcp-server": {
         "command": "/opt/homebrew/bin/npx",
         "args": [
           "tsx",
           "/path/to/your/omise-mcp/src/index.ts"
         ],
         "cwd": "/path/to/your/omise-mcp/",
         "env": {
           "NODE_ENV": "staging",
           "OMISE_ENVIRONMENT": "test",
           "OMISE_API_VERSION": "2019-05-29",
           "OMISE_PUBLIC_KEY": "<<YOUR_PUBLIC_KEY>>",
           "OMISE_SECRET_KEY": "<<YOUR_SECRET_KEY>>",
           "OMISE_BASE_URL": "https://api.staging-omise.co",
           "OMISE_VAULT_URL": "https://vault.staging-omise.co",
           "OMISE_TIMEOUT": "30000",
           "OMISE_RETRY_ATTEMPTS": "3",
           "OMISE_RETRY_DELAY": "1000",
           "SERVER_NAME": "omise-mcp-server-staging",
           "SERVER_VERSION": "1.0.0",
           "TOOLS": "all",
           "LOG_LEVEL": "info",
           "LOG_FORMAT": "json",
           "LOG_REQUESTS": "true",
           "LOG_RESPONSES": "false",
           "RATE_LIMIT_ENABLED": "true",
           "RATE_LIMIT_MAX_REQUESTS": "500",
           "RATE_LIMIT_WINDOW_MS": "60000"
         }
       }
     }
   }
   

   注: /path/to/your/omise-mcp/src/index.tsを、ダウンロードしたomise-mcpフォルダ内のindex.tsファイルへの実際のパスに置き換え、/path/to/your/omise-mcp/をomise-mcpフォルダへの正確なパスに置き換えてください。
   
   APIキー: <<YOUR_PUBLIC_KEY>>および<<YOUR_SECRET_KEY>>を実際のOmise APIキーに置き換えてください。これらはOmiseダッシュボード → 設定 → キーから取得できます。ライブアカウントの場合はライブキーを、テストアカウントの場合はテストキーを使用してください。

6. ファイルを保存して閉じます。
7. Claude Desktopを再起動します。
8. 設定 → 開発者に移動すると、Omise MCPサーバーが実行中でClaudeに接続されていることが確認できます。
   
9. Claudeチャットインターフェースから、検索とツールアイコンをクリックします。omise-mcp-serverが有効になっているはずです。
   

Cursor

CursorでOmise MCPをセットアップするには:

1. Cursor AIをダウンロード
2. Cursor APIにログイン
3. Cursor → 設定 → Cursor設定 → ツールとMCPに移動
4. MCPサーバーを追加をクリック
5. 以下のように設定を入力します:

   {
     "mcpServers": {
       "omise-mcp-server": {
         "command": "/path/to/npx",
         "args": [
           "tsx",
           "/path/to/your/omise-mcp/src/index.ts"
         ],
         "cwd": "/path/to/your/omise-mcp",
         "env": {
           "NODE_ENV": "staging",
           "OMISE_ENVIRONMENT": "test",
           "OMISE_API_VERSION": "2019-05-29",
           "OMISE_PUBLIC_KEY": "<<YOUR_PUBLIC_KEY>>",
           "OMISE_SECRET_KEY": "<<YOUR_SECRET_KEY>>",
           "OMISE_BASE_URL": "https://api.staging-omise.co",
           "OMISE_VAULT_URL": "https://vault.staging-omise.co",
           "OMISE_TIMEOUT": "30000",
           "OMISE_RETRY_ATTEMPTS": "3",
           "OMISE_RETRY_DELAY": "1000",
           "SERVER_NAME": "omise-mcp-server-staging",
           "SERVER_VERSION": "1.0.0",
           "TOOLS": "all",
           "LOG_LEVEL": "info",
           "LOG_FORMAT": "json",
           "LOG_REQUESTS": "true",
           "LOG_RESPONSES": "false",
           "RATE_LIMIT_ENABLED": "true",
           "RATE_LIMIT_MAX_REQUESTS": "500",
           "RATE_LIMIT_WINDOW_MS": "60000"
         }
       }
     }
   }
   

   注:

   • /path/to/npxをnpx実行可能ファイルへの実際のパス(例: /Users/username/.asdf/shims/npxまたは/opt/homebrew/bin/npx)に置き換えてください
   • /path/to/your/omise-mcp/src/index.tsをindex.tsファイルへの実際のパスに置き換えてください
   • /path/to/your/omise-mcpをomise-mcpフォルダへの実際のパスに置き換えてください
   • <<YOUR_PUBLIC_KEY>>および<<YOUR_SECRET_KEY>>をOmiseダッシュボード → 設定 → キーから取得した実際のOmise APIキーに置き換えてください

6. 設定を保存します
7. Cursorを再起動します
8. 設定 → Cursor設定 → ツールとMCPに移動します。Omise MCPサーバーが有効になっているはずです。
   

CLI

次のコマンドでMCPサーバーをローカルで起動します:

cd /path/to/your/omise-mcp
npx tsx src/index.ts

サーバーを実行する前に、OMISE_SECRET_KEYおよびOMISE_PUBLIC_KEY環境変数が設定されていることを確認してください。

設定パラメータ

設定パラメータを理解することで、特定のニーズに合わせてMCPサーバーをカスタマイズできます:

コア設定

URL設定

ネットワーク設定

サーバー設定

アクセス制御設定

アクセス制御機能:

• ツールホワイトリスト: TOOLS環境変数で指定されたツールのみがMCPクライアントに公開されます
• 厳密な検証: ツール名は起動時に50以上の利用可能なツールの完全なリストに対して検証されます
• ランタイム適用: 許可されていないツール呼び出しは構造化されたエラーメッセージで拒否されます
• 起動時検証: 無効なツール名が提供された場合、サーバーは起動に失敗します

例:

# すべてのツールを有効化
TOOLS=all

# 特定のツールのみを有効化
TOOLS=create_charge,retrieve_charge,list_charges

# 無効なツール名は起動失敗を引き起こす
TOOLS=invalid_tool # ❌ "Invalid tool names" エラーで失敗

環境別設定サンプル

開発環境:

{
  "NODE_ENV": "development",
  "OMISE_ENVIRONMENT": "test",
  "OMISE_PUBLIC_KEY": "pkey_test_...",
  "OMISE_SECRET_KEY": "skey_test_...",
  "TOOLS": "all",
  "LOG_LEVEL": "debug",
  "LOG_REQUESTS": "true",
  "LOG_RESPONSES": "true"
}

ステージング環境:

{
  "NODE_ENV": "staging",
  "OMISE_ENVIRONMENT": "test",
  "OMISE_BASE_URL": "https://api.staging-omise.co",
  "OMISE_VAULT_URL": "https://vault.staging-omise.co",
  "TOOLS": "all",
  "LOG_LEVEL": "info"
}

本番環境:

{
  "NODE_ENV": "production",
  "OMISE_ENVIRONMENT": "production",
  "OMISE_PUBLIC_KEY": "pkey_live_...",
  "OMISE_SECRET_KEY": "skey_live_...",
  "TOOLS": "create_charge,retrieve_charge,list_charges,create_customer,retrieve_customer",
  "LOG_LEVEL": "warn",
  "LOG_RESPONSES": "false",
  "RATE_LIMIT_MAX_REQUESTS": "1000"
}

ツール

サーバーは以下のMCPツールを公開します。プロンプトインジェクション攻撃を回避するため、Omise MCPを他のサーバーと使用する際は注意してください。特にチャージの作成や決済処理などの機密性の高い操作については、実行前に必ず操作内容を確認してください。フィードバックがある場合や、より多くのツールをご覧になりたい場合は、mcp@omise.coまでメールでお問い合わせください。

ログ設定

レート制限設定

利用可能なツール

Omise MCPサーバーは、Omise APIの機能にアクセスするための包括的なツールセットを提供します。各ツールは特定のAPIエンドポイントに対応し、決済、顧客、および関連リソースの管理を可能にします。

アカウント

アカウント情報と設定を取得および更新します。

バランス

Omiseアカウントの残高情報を取得します。

チャージ

決済チャージを作成、取得、管理します。

トークン

安全なカードトークン化用のトークンを作成します。

ソース

代替決済方法用のソースを作成および管理します。

カスタマー

カスタマーレコードとその決済方法を管理します。

カード

カスタマーに関連付けられたカードを管理します。

トランスファー

受取人への資金移動を作成および管理します。

受取人

資金を受け取る受取人を管理します。

返金

チャージ返金を作成および管理します。

ディスピュート

決済ディスピュートを管理し対応します。

ドキュメント

ディスピュート証拠ドキュメントをアップロードおよび管理します。

スケジュール

定期決済スケジュールを作成および管理します。

オカレンス

スケジュール済み決済オカレンスを取得します。

イベント

トランザクション監視用のWebhookイベントを取得します。

トランザクション

アカウント残高に影響を与えるトランザクション記録を取得します。

レシート

日次手数料レシートを取得します。

検索

複数のリソースタイプを横断して検索します。

サポートされているスコープ: charge、customer、dispute、recipient、refund、transfer |

外国為替

複数通貨トランザクションの為替レートを取得します。

機能

アカウント機能と利用可能な決済方法を取得します。

決済方法

Omise MCPサーバーは、Omise APIを通じて利用可能な幅広い決済方法をサポートしています:

• クレジット/デビットカード: Visa、Mastercard、JCB
• インターネットバンキング: バンコク銀行、カシコン銀行、サイアム商業銀行、クルンタイ銀行など
• モバイルバンキング: PromptPay、TrueMoney Wallet
• Eウォレット: Alipay、Alipay HK
• 分割払い: 月次払いを提供する各種銀行

サポートされている決済方法の完全なリストと国別の利用可能性については、retrieve_capabilityツールを使用してください。

セキュリティのベストプラクティス

Omise MCPサーバーを使用する際:

1. 開発中はテストキーを使用: 開発およびテスト中は常にテストモードのAPIキー(skey_test_およびpkey_test_で始まる)を使用してください。
2. APIキーを保護: APIキーをバージョン管理にコミットしたり、公開したりしないでください。環境変数として保存してください。
3. 適切なエラー処理を実装: 常にエラーを適切に処理し、エラーメッセージで機密情報を公開しないでください。
4. 不審なアクティビティを監視: API使用状況を定期的に確認し、異常なパターンに対するアラートを設定してください。
5. 本番環境でツールホワイトリストを使用: TOOLS=allを使用する代わりに、アプリケーションに必要なツールのみを指定してください。これは最小権限の原則に従い、攻撃対象領域を削減します。

エラー処理

Omise MCPサーバーは、API呼び出しが失敗した場合に詳細なエラー情報を提供します。例:

{
  "error": {
    "object": "error",
    "location": "https://docs.omise.co/api-errors",
    "code": "invalid_card",
    "message": "number is invalid"
  }
}

一般的なエラーコード:

• authentication_failure - 無効なAPIキー
• invalid_card - カード検証失敗
• insufficient_fund - 操作に十分な残高がない
• failed_processing - 決済処理失敗
• invalid_charge - 無効なチャージパラメータ
• not_found - リソースが見つからない
• service_not_available - サービス一時的に利用不可

エラーコードの完全なリストについては、Omise APIエラードキュメントを参照してください。

テスト

テストモード

すべてのOmiseアカウントはデフォルトでテストモードが有効になっています。テストAPIキーを使用して、実際の決済を処理することなくトランザクションをシミュレートします。

テストカード

テストモードで以下のテストカード番号を使用します:

成功するチャージ: - 4242424242424242 - Visa - 5555555555554444 - Mastercard - 3530111333300000 - JCB

失敗するチャージ: - 4000000000000002 - カード拒否 - 4000000000000069 - 期限切れカード - 4000000000000127 - 誤ったCVC

テストカードと失敗シナリオの完全なリストについては、Omiseテストガイドを参照してください。

APIバージョン管理

Omise APIは後方互換性を確保するためにバージョン管理を使用しています。現在推奨されているバージョンは2019-05-29です。

特定のAPIバージョンを使用するには、OMISE_API_VERSION環境変数を設定します:

OMISE_API_VERSION=2019-05-29

詳細については、Omise APIバージョン管理ドキュメントを参照してください。

Claudeでの使用例

TOKENを使用したチャージの作成

チャージの作成と返金

利用可能なツールの一覧表示

サポート

問題が発生した場合や質問がある場合:

• ドキュメント: https://docs.omise.co
• APIステータス: https://status.omise.co
• サポートメール: support@omise.co
• GitHub Issues: https://github.com/OmisePayments/omise-mcp/issues

関連情報

• Omise APIドキュメント
• 決済方法ガイド
• セキュリティのベストプラクティス
• Webhookイベント
• テストガイド
• APIエラー