编号-mcp

](https://www.npmjs.com/package/nomba-mcp) ![License: MIT](https://opensource.org/licenses/MIT)

MCP（模型上下文协议）服务器 Nomba API.将任何兼容MCP的AI助手连接到您的Nomba商业账户，以检查余额、汇款、生成支付链接、管理虚拟账户、购买通话时间、支付水电费等。

适用于任何MCP客户端，包括Claude Desktop、Claude Code、Cursor、Windsurf、Cline和其他MCP兼容工具。

该服务器基于Nomba的v1 API和OAuth2身份验证，提供41种工具，涵盖账户、子账户、终端、转账、在线结账、虚拟账户、交易、账单（电力、有线电视、博彩）和播放时间/数据。

注：服务器默认为沙盒环境。沙盒模式下的所有交易都使用测试数据，不会转移真实资金。集 NOMBA_BASE_URL=https://api.nomba.com 只有当你准备好开始生活的时候。

特性

账户和终端 -查看父账户详细信息，检查余额，列出/分配/取消分配POS终端
子账户 -创建、列出、更新、暂停和重新激活具有独立余额的子帐户
转账 -银行列表查找、账户验证、银行转账、Nomba账户之间的内部转账
在线结账 -支付链接、代币化卡费用、退款、交易状态、取消
虚拟账户 -创建、更新、过期和列出用于接收付款的虚拟银行帐户
交易 -交易历史、按类型/日期过滤、单笔交易详细信息、状态查询
账单-电力 -列出供应商、验证仪表编号、购买代币（预付/后付费）
账单-有线电视 -列出提供商、验证智能卡、付费订阅（DSTV、GOtv、四达时代）
票据-投注 -列出提供商、基金投注账户
通话时间和数据 -购买通话时间、列出数据套餐、购买数据套餐（MTN、Airtel、Glo、9mobile）

安全

该服务器包括用于金融操作的内置安全保护措施：

支出限额 -可配置每笔交易的最高限额和会话支出上限
重复检测 -在60秒内阻止相同的交易（相同金额+收款人）
PII编辑 -BVN、银行账号和卡令牌在返回给AI之前会被屏蔽
日志编辑 -敏感字段（帐号、电话号码、电子邮件）在日志输出中被屏蔽
HTTPS强制 -除非明确覆盖，否则拒绝从非HTTPS基本URL开始
生产保障 -需要明确选择使用生产API
工具注释 -所有工具都带有注释 destructiveHint/readOnlyHint 因此，MCP客户端可以强制执行财务操作的确认对话框
路径遍历保护 -对API路径中使用的所有ID字段进行严格验证

先决条件

你需要 Nomba API证书 从 Nomba开发者仪表板:

客户端ID -您的API客户端ID
客户端密钥 -您的API客户端机密
帐户ID -您的父帐户ID（UUID格式）

身份验证是自动处理的。服务器在第一个请求上获得OAuth2访问令牌，并使用刷新令牌端点透明地刷新它。

安装

使用npx（推荐）

npx nomba-mcp

也可用作 @nomba-inc/mcp-server:

npx @nomba-inc/mcp-server

全局安装

npm install -g nomba-mcp

从源代码构建

git clone https://github.com/samaxbytez/nomba-mcp.git
cd nomba-mcp
npm install
npm run build
node build/index.js

配置

环境变量

变量	必填	默认	描述
`NOMBA_CLIENT_ID`	是	--	您在Nomba开发人员仪表板上的客户ID
`NOMBA_CLIENT_SECRET`	是	--	您在Nomba开发人员仪表板上的客户机密
`NOMBA_ACCOUNT_ID`	是	--	您的父帐户ID（UUID格式）
`NOMBA_BASE_URL`	没有	`https://sandbox.nomba.com`	API基本URL。设置为 `https://api.nomba.com` 用于生产
`NOMBA_MAX_TRANSACTION`	没有	`100000`	每笔交易允许的最大金额（NGN）
`NOMBA_SESSION_SPENDING_CAP`	没有	`500000`	每次会话的最大累计支出（NGN）
`NOMBA_PRODUCTION_CONFIRMED`	否	--	必须是 `true` 使用时 `api.nomba.com`
`NOMBA_ALLOW_INSECURE`	否	--	设置为 `true` 允许非HTTPS URL（仅限本地开发人员）

克劳德桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "nomba": {
      "command": "npx",
      "args": ["-y", "nomba-mcp"],
      "env": {
        "NOMBA_CLIENT_ID": "your_client_id",
        "NOMBA_CLIENT_SECRET": "your_client_secret",
        "NOMBA_ACCOUNT_ID": "your_account_id"
      }
    }
  }
}

克劳德代码

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "nomba": {
      "command": "npx",
      "args": ["-y", "nomba-mcp"],
      "env": {
        "NOMBA_CLIENT_ID": "your_client_id",
        "NOMBA_CLIENT_SECRET": "your_client_secret",
        "NOMBA_ACCOUNT_ID": "your_account_id"
      }
    }
  }
}

光标/风帆

添加到MCP设置（设置>MCP服务器）：

{
  "nomba": {
    "command": "npx",
    "args": ["-y", "nomba-mcp"],
    "env": {
      "NOMBA_CLIENT_ID": "your_client_id",
      "NOMBA_CLIENT_SECRET": "your_client_secret",
      "NOMBA_ACCOUNT_ID": "your_account_id"
    }
  }
}

任何MCP客户端

设置环境变量并运行：

NOMBA_CLIENT_ID=your_id NOMBA_CLIENT_SECRET=your_secret NOMBA_ACCOUNT_ID=your_account npx nomba-mcp

服务器使用标准MCP传输通过stdio进行通信，因此它可以与支持MCP协议的任何客户端一起工作。

建筑

nomba-mcp/
├── src/
│   ├── index.ts              # Entry point, server setup, spending guard config
│   ├── client.ts             # Nomba API client (OAuth2 token + refresh management)
│   ├── utils.ts              # Shared utilities (jsonResponse, logToolCall, safeId)
│   ├── redact.ts             # Response field filtering (BVN, account numbers, card tokens)
│   ├── spending-guard.ts     # Transaction limits, session caps, duplicate detection
│   ├── resources/
│   │   └── bank-list.ts      # Cached bank code list (MCP resource, 24h TTL)
│   └── tools/
│       ├── accounts.ts       # Parent account details, balance, terminals
│       ├── sub-accounts.ts   # Sub-account CRUD, balance, suspend, reactivate
│       ├── transfers.ts      # Bank list, account lookup, bank/internal transfers
│       ├── checkout.ts       # Payment links, tokenized cards, refunds
│       ├── virtual-accounts.ts  # Virtual account CRUD and listing
│       ├── transactions.ts   # Transaction history, details, filtering, requery
│       ├── airtime.ts        # Airtime and data bundles
│       └── bills/
│           ├── index.ts      # Hub re-exporting all bill tool registrations
│           ├── electricity.ts  # Electricity providers, meter lookup, token purchase
│           ├── cable.ts      # Cable TV providers, smartcard lookup, subscriptions
│           └── betting.ts    # Betting providers, account funding
├── package.json
├── tsconfig.json
└── README.md

设计决策：

使用OAuth2客户端凭据，并通过以下方式自动刷新令牌 /v1/auth/token/refresh 401自动重试
当多个工具并行执行时，promise锁会阻止并发令牌刷新
金融工具由共享 SpendingGuard 具有可配置限制的实例
敏感数据（BVN、银行账号、卡令牌）在到达AI之前从API响应中进行编辑
账单被拆分为子文件（电力、电缆、博彩），并有一个干净的组织中心
银行列表作为MCP资源公开，具有24小时缓存TTL
所有标有MCP的工具 destructiveHint/readOnlyHint 用于客户端确认执行
工具名称前缀为 nomba_ 避免与其他MCP服务器发生冲突

工具参考

账户和终端（5个工具）

工具	描述	API端点
`nomba_get_parent_account`	获取父账户详细信息（ID、名称、类型、状态、关联银行）	`GET /v1/accounts/parent`
`nomba_get_parent_balance`	获取母账户当前余额（NGN）	`GET /v1/accounts/parent/balance`
`nomba_list_terminals`	列出分配给该账户的所有POS终端	`GET /v1/accounts/terminals`
`nomba_assign_terminal`	按ID和序列号分配POS终端	`POST /v1/terminals/assign`
`nomba_unassign_terminal`	取消分配POS终端	`POST /v1/terminals/unassign`

子账户（7个工具）

工具	描述	API端点
`nomba_create_sub_account`	使用名称、可选电子邮件/电话创建新的子帐户	`POST /v1/accounts`
`nomba_list_sub_accounts`	列出所有分页的子帐户	`GET /v1/accounts`
`nomba_get_sub_account`	获取特定子账户的详细信息	`GET /v1/accounts/{accountId}`
`nomba_get_sub_account_balance`	获取子账户的当前余额	`GET /v1/accounts/{accountId}/balance`
`nomba_update_sub_account`	更新子帐户名称、电子邮件或电话	`PUT /v1/accounts/{accountId}`
`nomba_suspend_sub_account`	暂停子账户（阻止所有交易）	`PUT /v1/accounts/{accountId}/suspend`
`nomba_reactivate_sub_account`	重新激活以前暂停的子帐户	`PUT /v1/accounts/{accountId}/reactivate`

转账（4个工具）

工具	描述	API端点
`nomba_list_banks`	获取所有尼日利亚银行代码和名称	`GET /v1/transfers/banks`
`nomba_lookup_bank_account`	验证账号并获取持有人姓名（转账前致电）	`POST /v1/transfers/bank-account-lookup`
`nomba_transfer_to_bank`	将资金转入尼日利亚的外部银行账户	`POST /v1/transfers/to-banks`
`nomba_transfer_between_accounts`	在Nomba账户之间转账（例如，母账户到子账户）	`POST /v1/transfers/between-accounts`

在线结账（5个工具）

工具	描述	API端点
`nomba_create_checkout_order`	创建支付链接（卡、银行转账或USSD）	`POST /v1/checkout/order`
`nomba_charge_tokenized_card`	向以前保存的卡收取定期付款的费用	`POST /v1/checkout/charge-tokenized-card`
`nomba_refund_transaction`	处理结账交易的全部或部分退款	`POST /v1/checkout/refund`
`nomba_get_checkout_transaction`	获取结账交易详细信息和状态	`GET /v1/checkout/order/{orderReference}`
`nomba_cancel_transaction`	取消未完成/待处理的结账交易	`POST /v1/checkout/cancel-transaction`

虚拟账户（5个工具）

工具	描述	API端点
`nomba_create_virtual_account`	创建新的虚拟银行账户	`POST /v1/accounts/virtual`
`nomba_get_virtual_account`	获取虚拟账户详细信息和余额	`GET /v1/accounts/virtual/{accountId}`
`nomba_update_virtual_account`	更新帐户名或回调URL	`PATCH /v1/accounts/virtual/{accountId}`
`nomba_expire_virtual_account`	永久停用虚拟帐户	`POST /v1/accounts/virtual/{accountId}/expire`
`nomba_list_virtual_accounts`	列出所有带分页的虚拟帐户	`GET /v1/accounts/virtual`

交易（4种工具）

工具	描述	API端点
`nomba_list_bank_transactions`	列出交易历史记录，并可选择日期过滤	`GET /v1/transactions/bank`
`nomba_requery_transaction`	按会话ID检查交易状态	`POST /v1/transactions/accounts`
`nomba_get_transaction`	获取单个交易的完整详细信息	`GET /v1/transactions/{transactionId}`
`nomba_filter_transactions`	按类型（CREDIT/DEBIT）、日期范围筛选交易	`GET /v1/transactions/filter`

账单-电力（3个工具）

工具	描述	API端点
`nomba_get_electricity_providers`	列出可用的配电公司	`GET /v1/bills/electricity/providers`
`nomba_lookup_electricity_customer`	验证仪表编号并获取客户名称	`POST /v1/bills/electricity/customer-lookup`
`nomba_buy_electricity`	购买电力代币（预付）或支付账单（后付费）	`POST /v1/bills/electricity/pay`

账单-有线电视（3个工具）

工具	描述	API端点
`nomba_get_cable_providers`	列出可用的有线电视提供商（DSTV、GOtv、四达时代）	`GET /v1/bills/cabletv/providers`
`nomba_lookup_cable_customer`	验证智能卡/IUC号码并获取客户姓名	`POST /v1/bills/cabletv/customer-lookup`
`nomba_pay_cable_subscription`	支付有线电视订阅费	`POST /v1/bills/cabletv/pay`

票据-投注（2个工具）

工具	描述	API端点
`nomba_get_betting_providers`	列出可用的投注平台	`GET /v1/bills/betting/providers`
`nomba_fund_betting_account`	为客户的投注账户充值	`POST /v1/bills/betting/pay`

通话时间和数据（3个工具）

工具	描述	API端点
`nomba_buy_airtime`	购买尼日利亚电话号码（MTN、Airtel、Glo、9mobile）的通话时间	`POST /v1/bills/airtime/pay`
`nomba_list_data_plans`	列出网络提供商的可用数据计划	`GET /v1/bills/data/plans`
`nomba_buy_data`	购买电话号码的数据包	`POST /v1/bills/data/pay`

资源

`nomba://banks`

JSON格式的所有尼日利亚银行代码和名称的缓存列表。提取一次并缓存24小时。客户端可以读取此资源，而不是调用 nomba_list_banks 以避免重复API调用。

示例提示

“我的Nomba账户余额是多少？”
“列出我的所有子帐户”
“将5000奈拉转账至GTBank账户0123456789”
“在Access Bank查询帐户0123456789”
“为10000奈拉创建支付链接customer@email.com"
“显示我最近10笔交易”
“显示2024年1月以来的所有信用交易”
创建一个名为“John Doe Payments”的虚拟账户
“购买1000奈拉通话时间08012345678”
“有哪些MTN数据计划可用？”
“在Ikeja Electric预付费的12345678电表上购买5000奈拉电力”
“列出有线电视提供商”

发展

构建

npm run build

运行测试

npm test

观看模式

npm run test:watch

棉绒

npm run lint

格式

npm run format

MCP检验员测试

NOMBA_CLIENT_ID=your_id NOMBA_CLIENT_SECRET=your_secret NOMBA_ACCOUNT_ID=your_account_id \
npx @modelcontextprotocol/inspector node build/index.js

添加新工具

在中创建新文件 src/tools/ 或添加到现有类别
遵循以下模式： registerXxxTools(server, client) 或 registerXxxTools(server, client, guard) 金融工具
在中导入并调用register函数 src/index.ts
添加 annotations 与适当 readOnlyHint/destructiveHint 价值观
在中添加测试 src/tools/tools.test.ts
更新此自述文件

故障排除

“缺少必需的环境变量”

确保 NOMBA_CLIENT_ID, NOMBA_CLIENT_SECRET，以及 NOMBA_ACCOUNT_ID 在MCP服务器配置中设置 env 钥匙。

“NOMBA_BASE_URL必须使用HTTPS”

默认情况下，服务器需要HTTPS。对于本地开发，set NOMBA_ALLOW_INSECURE=true.

“基本URL指向生产”

集 NOMBA_PRODUCTION_CONFIRMED=true 以确认您打算使用API生产。

“令牌发放失败（401）”

您的客户端凭据无效。验证您的 NOMBA_CLIENT_ID 和 NOMBA_CLIENT_SECRET 在 Nomba开发者仪表板.

“令牌发放失败（403）”

您的帐户可能没有所需的API权限。检查您的Nomba仪表板以了解访问设置。

“Nomba API…失败（429）”

您已达到速率限制（默认每秒15个POST请求）。请稍等，然后重试。

“金额超过每笔交易限额”

交易超过 NOMBA_MAX_TRANSACTION （默认100000 NGN）。如果需要，通过环境变量增加限制。

“超出会话支出上限”

累计支出已超过 NOMBA_SESSION_SPENDING_CAP （默认值为500000 NGN）。重新启动服务器以重置会话计数器，或增加上限。

沙盒vs生产

服务器默认为沙盒(https://sandbox.nomba.com).要使用生产，请同时设置 NOMBA_BASE_URL=https://api.nomba.com 和 NOMBA_PRODUCTION_CONFIRMED=true.

工具未出现

更新配置后重新启动MCP客户端
验证您的配置使用情况 "command": "npx" 和 "args": ["-y", "nomba-mcp"]

许可证

麻省理工学院

Nomba MCP

快速接入

详细介绍