interswitch-mcp-server

Interswitch MCP 服务

一个 Model Context Protocol（MCP） 服务，可让 AI 助手通过 Interswitch API 处理支付、转账、VAS、无卡支付码、交易搜索、Card 360、借贷、付款、代理银行业务和金融科技卡处理工具。

警告

**公开预览：**此 MCP 服务目前处于公开预览阶段。它同时支持 Interswitch 沙盒和生产环境，请谨慎使用，先从只读模式开始，并报告遇到的任何问题。

快速开始

通过 npm 安装并运行（推荐）：

npx interswitch-mcp-server

或全局安装：

npm install -g interswitch-mcp-server
interswitch-mcp-server

或者克隆并构建以进行本地开发：

git clone https://github.com/Dairus01/Interswitch-mcp-server.git
cd Interswitch-mcp-server
npm install
npm run build

然后配置 MCP 客户端以使用此服务（请参阅客户端集成）。

要求

• Node.js v18+
• npm 或 yarn
• 要使用的各个域的 Interswitch API 凭据
• 根据使用场景所需的 Interswitch 商户、应付、发起实体、终端或特定域标识符

配置选项

环境变量	用途
INTERSWITCH_CLIENT_ID	用于支付、转账、VAS、无卡支付、借贷、转账服务和付款的核心 OAuth2 客户端 ID
INTERSWITCH_CLIENT_SECRET	核心 OAuth2 客户端密钥
INTERSWITCH_ENV	API 环境：sandbox 或 production；默认为 sandbox
INTERSWITCH_READ_ONLY	设置为 true 可在任何 API 调用前阻止写入工具；默认为 false
INTERSWITCH_REQUIRE_CONFIRMATION	兼容性设置。工具确认由工具模式和风险级别强制执行。
INTERSWITCH_MERCHANT_CODE	需要此代码的支付操作所用的商户代码
INTERSWITCH_PAYABLE_CODE	需要此代码的支付操作所用的应付代码
INTERSWITCH_INITIATING_ENTITY_CODE	转账操作所用的发起实体代码
INTERSWITCH_TERMINAL_ID	需要终端标识的操作所用的终端 ID
CARD360_CLIENT_ID	单独的 Card 360 客户端 ID
CARD360_CLIENT_SECRET	单独的 Card 360 客户端密钥
CARD360_RSA_PUBLIC_KEY	用于在本地加密 Card 360 PIN 载荷的 RSA 公钥
TRANSACTION_SEARCH_CLIENT_ID	单独的交易搜索客户端 ID
TRANSACTION_SEARCH_CLIENT_SECRET	单独的交易搜索客户端密钥
INTERSWITCH_AGENCY_MERCHANT_ID	代理银行业务商户标识符
INTERSWITCH_AGENCY_TERMINAL_ID	代理银行业务终端标识符
INTERSWITCH_LEGACY_AUTH_ENABLED	启用受支持的、基于 InterswitchAuth 的旧版流程
DEBUG	启用调试日志记录。请避免在生产环境中使用。

可通过 INTERSWITCH_ENV 选择 API 环境：

1. 沙盒（默认）： INTERSWITCH_ENV=sandbox
2. 生产： INTERSWITCH_ENV=production

**安全说明：**生产模式使用真实的 Interswitch 生产端点。如果 INTERSWITCH_ENV=production、已配置有效的生产凭据、INTERSWITCH_READ_ONLY=false，并且调用写入工具时传入 confirm: true，服务就可以发起真实的生产 API 调用。

首次设置时，为了更加安全，请从只读模式开始：

INTERSWITCH_ENV=production \
INTERSWITCH_READ_ONLY=true \
INTERSWITCH_CLIENT_ID=your_production_client_id \
INTERSWITCH_CLIENT_SECRET=your_production_client_secret \
interswitch-mcp-server

在获得授权并准备好允许实时写入后，设置：

INTERSWITCH_READ_ONLY=false

客户端集成

Interswitch MCP 服务可与任何兼容 MCP 的客户端配合使用。以下是大多数客户端（Claude Desktop、ChatGPT Desktop、Cursor、Windsurf、VS Code、Claude Code 等）使用的标准配置架构。

使用 npm（推荐）

对于通过 npm 安装的服务：

{
  "mcpServers": {
    "interswitch": {
      "command": "npx",
      "args": ["-y", "interswitch-mcp-server"],
      "env": {
        "INTERSWITCH_ENV": "sandbox",
        "INTERSWITCH_READ_ONLY": "true",
        "INTERSWITCH_CLIENT_ID": "your_client_id",
        "INTERSWITCH_CLIENT_SECRET": "your_client_secret",
        "INTERSWITCH_MERCHANT_CODE": "your_merchant_code",
        "INTERSWITCH_PAYABLE_CODE": "your_payable_code",
        "INTERSWITCH_INITIATING_ENTITY_CODE": "your_entity_code"
      }
    }
  }
}

在生产环境中，请有意修改环境变量值：

{
  "mcpServers": {
    "interswitch": {
      "command": "npx",
      "args": ["-y", "interswitch-mcp-server"],
      "env": {
        "INTERSWITCH_ENV": "production",
        "INTERSWITCH_READ_ONLY": "true",
        "INTERSWITCH_CLIENT_ID": "your_production_client_id",
        "INTERSWITCH_CLIENT_SECRET": "your_production_client_secret",
        "INTERSWITCH_MERCHANT_CODE": "your_production_merchant_code",
        "INTERSWITCH_PAYABLE_CODE": "your_production_payable_code",
        "INTERSWITCH_INITIATING_ENTITY_CODE": "your_production_entity_code"
      }
    }
  }
}

使用本地构建

如果你已克隆并在本地构建了服务：

{
  "mcpServers": {
    "interswitch": {
      "command": "node",
      "args": ["/path/to/Interswitch-mcp-server/dist/index.js"],
      "env": {
        "INTERSWITCH_ENV": "sandbox",
        "INTERSWITCH_READ_ONLY": "true",
        "INTERSWITCH_CLIENT_ID": "your_client_id",
        "INTERSWITCH_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

重要

设置 command: "node" 时，请确保使用的是 Node v18+。如果你使用包管理器，可能需要在命令行中运行以下命令来获取 Node 二进制文件的路径：

Linux 和 MacOS

which node

Windows

where node

获取路径后，将其用作 JSON 配置中 MCP 服务命令的值。例如：command: "path/to/installation/bin/node"

在哪里添加此配置

客户端	配置文件位置
VS Code	.vscode/mcp.json
Claude Desktop	claude_desktop_config.json
ChatGPT Desktop	应用偏好设置中的 MCP 设置
Cursor	.cursor/mcp.json 或全局 MCP 设置
Windsurf	设置中的 MCP 配置
Claude Code	~/.claude/mcp.json 或项目级 .mcp.json

工作原理

Interswitch MCP 服务通过专用 MCP 工具向 AI 助手开放 Interswitch API 域。该服务不会在运行时解析 OpenAPI 文件，而是为受支持的 Interswitch 域提供经过整理的类型化工具。

架构图

graph TD
    subgraph MCP Server
        A[Interswitch MCP Server]
        B[Tool Registry]
        C[Resource Registry]
    end

    subgraph Auth Layer
        D[OAuth2 Passport Manager]
        E[Card 360 Token Manager]
        F[Transaction Search Manager]
        G[Agency Banking Token Manager]
        H[Legacy Auth Manager]
    end

    subgraph Core Services
        I[Payments Service]
        J[VAS Services]
        K[Transfers Service]
        L[Cardless Services]
        M[Transaction Search Service]
        N[Card 360 Service]
        O[Lending Service]
        P[Transfer Service]
        Q[Payouts Service]
        R[Agency Service]
        S[Fintech Utilities]
    end

    subgraph Safety Layer
        J1[Confirmation Gate]
        J2[Read-Only Mode]
        J3[Redaction System]
        J4[Audit Logging]
    end

    A --> B
    A --> C
    A --> D
    A --> E
    A --> F
    A --> G
    A --> H
    B --> I
    B --> J
    B --> K
    B --> L
    B --> M
    B --> N
    B --> O
    B --> P
    B --> Q
    B --> R
    B --> S
    I --> J1
    J --> J1
    K --> J1
    L --> J1
    M --> J1
    N --> J1
    O --> J1
    P --> J1
    Q --> J1
    R --> J1
    S --> J1
    J1 --> J2
    J2 --> J3
    J3 --> J4
    J4 --> Z[External APIs]
    
    style MCP Server fill:#f0f8ff,stroke:#333,stroke-width:2px
    style Auth Layer fill:#e6f7e6,stroke:#333,stroke-width:1px
    style Core Services fill:#f9f9f9,stroke:#666,stroke-width:1px
    style Safety Layer fill:#fff0f0,stroke:#c33,stroke-width:1px
    style Z fill:#d4d4d4,stroke:#999,stroke-dasharray: 5 5

每个工具都会：

1. 使用严格的架构验证输入
2. 应用确认和只读安全防护
3. 选择已配置的沙盒或生产环境基础 URL
4. 使用该域对应的认证系统
5. 仅在调用工具时才调用 Interswitch API
6. 对返回数据中的敏感字段进行脱敏
7. 返回标准化的 MCP 响应

认证系统

认证系统	用途
OAuth2 Passport	核心支付、转账、VAS、无卡服务、借贷、转账服务和付款
Card 360 令牌管理器	Card 360 操作
Transaction Search 令牌管理器	Transaction Search API
Legacy InterswitchAuth	启用时用于旧版签名请求流程
Agency Banking 令牌管理器	Agency Banking SOAP/XML 令牌流程

可用工具

工具	描述
isw_initialize_payment	初始化支付请求
isw_get_transaction_status	检查交易状态
isw_get_transaction_by_reference	按引用获取交易
isw_create_payment_link	创建支付链接
isw_initiate_refund	发起退款；高风险写入
isw_get_refund_status	检查退款状态
isw_pay_bill	支付账单
isw_get_billers	列出账单服务商
isw_get_biller_packages	列出账单服务商的套餐
isw_get_billers_by_category	按类别列出账单服务商
isw_get_biller_details	获取账单服务商详情
isw_validate_customer	验证账单服务商客户
isw_pay_vas_bill	支付 VAS 账单
isw_airtime_recharge	充值话费
isw_get_airtime_epins	请求话费 ePIN
isw_single_transfer	发送单笔银行转账；高风险写入
isw_bulk_transfer	发送批量转账；高风险写入；最多 100 笔交易
isw_resolve_bank_account	查询银行账户详情
isw_get_bank_codes	列出支持的银行代码
isw_agency_banking_cashout	发起代理银行取款；高风险写入
isw_create_paycode	创建无卡支付码
isw_create_bulk_paycodes	创建批量支付码；高风险写入；最多 100 个支付码
isw_get_paycode_status	检查支付码状态
isw_deactivate_paycode	停用支付码
isw_transaction_search_quick_search	使用快速搜索字段搜索交易
isw_transaction_search_reference_search	按交易引用搜索
isw_transaction_search_bulk_search	搜索多笔交易
isw_get_transaction_details	获取交易详细信息
isw_create_card	创建卡；高风险写入
isw_retry_card_creation	重试创建卡
isw_initiate_card_data_prep	发起卡数据准备
isw_fetch_data_prep_request	获取数据准备请求
isw_fetch_prepared_cards	获取已准备的卡
isw_bulk_card_production	开始批量制卡；高风险写入
isw_reissue_card_pin	重新签发卡 PIN；高风险写入
isw_change_card_pin	更改卡 PIN；高风险写入
isw_get_pin	在支持的情况下获取 PIN 相关响应；高风险读取
isw_block_card	冻结卡；高风险写入
isw_unblock_card	解冻卡；高风险写入
isw_block_prepaid_card	冻结预付卡；高风险写入
isw_unblock_prepaid_card	解冻预付卡；高风险写入
isw_link_card_to_account	将卡关联到账户；高风险写入
isw_check_prepaid_balance	检查预付卡余额
isw_check_debit_balance	检查借记卡余额
isw_confirm_prepaid_sufficient	确认预付卡余额充足
isw_confirm_debit_sufficient	确认借记卡余额充足
isw_fetch_cards_by_issuer	按发卡机构获取卡
isw_fetch_single_card_by_pan	按 PAN 获取单张卡，并对信息进行遮盖
isw_fetch_cards_by_account	按账户获取卡
isw_fetch_customer_card_details	获取客户卡详情
isw_fetch_request_logs	获取 Card 360 请求日志
isw_validate_card	验证卡数据
isw_request_nano_loan	申请小额贷款；高风险写入
isw_salary_lending	启动薪资贷款流程；高风险写入
isw_value_financing	启动价值融资流程；高风险写入
isw_get_customer_demographics	获取客户人口统计信息
isw_get_financial_history	获取客户财务历史记录
isw_get_financial_history_average	获取财务历史记录平均值
isw_get_financial_habits	获取客户财务习惯
isw_credit_inquiry	执行信用查询
isw_complete_credit	使用 OTP 完成授信；高风险写入
isw_requery_transfer	重新查询转账状态
isw_get_receiving_institutions	列出收款机构
isw_get_payout_channels	列出付款渠道
isw_agency_get_token	获取／缓存代理银行令牌
isw_fintech_validate_debit_payload	验证借记负载结构
isw_fintech_validate_reversal_payload	验证冲正负载结构
isw_fintech_validate_enquiry_payload	验证查询负载结构
isw_fintech_validate_place_lien_payload	验证设定留置权负载结构
isw_fintech_validate_debit_lien_payload	验证借记留置权负载结构
isw_fintech_compute_mac	计算 MAC；因接受密钥而属于高风险操作
isw_fintech_build_response	构建金融科技响应负载；提供密钥时属于高风险操作

可用资源

资源	URI	描述
response_codes	isw://response-codes	常见的 Interswitch 响应码参考
config_summary	isw://config-summary	安全的运行时配置摘要；仅返回凭据是否存在，不会返回机密

示例

当你向 AI 助手提出类似 “使用 Interswitch 为 [email protected] 初始化一笔 5000 NGN 的付款” 的请求时，幕后会发生以下情况：

1. 助手选择 isw_initialize_payment
2. 它传入明确的金额，例如 amountNaira: 5000
3. 对于写入操作，必须包含 confirm: true
4. 服务验证请求，在需要时安全地转换金额，使用 Interswitch 进行身份验证，并调用已配置的沙盒或生产环境端点
5. 你会收到经过规范化处理且原始数据已脱敏的响应

提示词建议

使用此 MCP 服务时，若要获得最佳结果，请在提示词中明确说明需求，并始终在请求中包含“Interswitch”。

好的提示词：

• “为 [email protected] 初始化一笔 50000 NGN 的 Interswitch 付款。”
• “查询参考编号为 order-1001 的 Interswitch 交易状态。”
• “使用银行代码 058 查询 Interswitch 银行账号 0123456789。”
• “使用 Interswitch 发起一笔 1000 NGN 的单笔转账，并设置 confirm true。”
• “读取 Interswitch 响应码资源。”

效果较差的提示词：

• “列出我的交易”（未说明使用哪项服务，也未提供参考编号或搜索条件）
• “转钱”（缺少收款人、银行、金额和确认详情）
• “支付这张账单”（缺少账单发行方、套餐、客户和金额详情）

明确说明需求可确保大模型快速找到合适的工具，并减少歧义。

生产环境安全

设置 INTERSWITCH_ENV=production 后，此服务可将请求路由至 Interswitch 生产环境端点。能否安全用于生产环境，取决于凭据是否正确、Interswitch 账号权限以及组织的运营管控措施。

服务内置的安全行为：

• 写入工具需要 confirm: true
• 高风险敏感读取工具需要 confirm: true
• INTERSWITCH_READ_ONLY=true 会在发起任何外部 API 调用前阻止所有写入操作
• 低风险读取操作无需确认
• 返回前会对原始响应进行脱敏
• 工具输出不会主动返回令牌和机密
• 配置所需 RSA 公钥后，卡 PIN 负载会在本地加密
• 生产环境启动警告会写入 stderr，不会静默隐藏风险配置

建议的生产环境上线步骤：

1. 配置生产环境凭据，但保持 INTERSWITCH_READ_ONLY=true
2. 检查启动警告和配置摘要
3. 先测试安全的只读工具
4. 确认拟使用工具对应的域凭据
5. 仅在已获准进行实时写入操作后，才将 INTERSWITCH_READ_ONLY=false
6. 对包含 confirm: true 的提示词进行人工审核

开发

在本地运行（无需构建）

进行本地开发和测试时，可以直接运行 TypeScript 源码：

npm run dev

使用 MCP Inspector 运行

npm run inspect

构建

npm run build

运行测试

npm test

类型检查

npm run lint

预览 npm 软件包内容

npm pack --dry-run

故障排查

问题	解决方案
服务在启动时静默退出	在终端中运行，并检查 stderr；确认 Node v18+ 且环境变量有效
出现生产环境警告	根据警告添加缺少的凭证组、设置 INTERSWITCH_READ_ONLY=true 或禁用 DEBUG
客户端中未显示工具	确保服务正在运行，且客户端配置路径正确
写入工具被阻止	传入 confirm: true；如果仍被阻止，请检查 INTERSWITCH_READ_ONLY
高风险读取被阻止	传入 confirm: true
支付工具失败	在需要时配置 INTERSWITCH_MERCHANT_CODE 和 INTERSWITCH_PAYABLE_CODE
转账工具失败	在需要时配置 INTERSWITCH_INITIATING_ENTITY_CODE
Card 360 工具失败	配置 CARD360_CLIENT_ID 和 CARD360_CLIENT_SECRET
PIN 操作失败	配置有效的 CARD360_RSA_PUBLIC_KEY
Transaction Search 失败	配置 TRANSACTION_SEARCH_CLIENT_ID 和 TRANSACTION_SEARCH_CLIENT_SECRET
Agency 工具失败	配置 INTERSWITCH_AGENCY_MERCHANT_ID 和 INTERSWITCH_AGENCY_TERMINAL_ID
请求超时	检查与已配置 Interswitch 环境的网络连接

贡献

欢迎提交拉取请求。对于重大更改，请先创建议题，讨论您希望进行的更改。

详情请参阅 CONTRIBUTING.md。

许可证

MIT