mcp-culqi

Name: mcp-culqi
Author: codespar

本地服务

github.com/codespar金融数据2754 周前更新

代码仓库

关于 mcp-culqi

mcp-culqi 是秘鲁支付服务商 Culqi 的 MCP 服务，覆盖收款、退款、银行卡、Yape/PagoEfectivo 与订阅等 20 个工具。适合需要在秘鲁接入支付能力的电商和 SaaS 项目。

主要功能

01卡支付的创建、捕获与退款
02客户与银行卡的保存及复用
03Yape、PagoEfectivo 等非卡支付订单
04订阅计划与订阅管理
05Webhook 事件查询

适用场景

01为秘鲁电商网站接入卡支付与退款处理
02通过已保存的银行卡管理 SaaS 周期性订阅
03为 Yape 或 PagoEfectivo 等非卡支付方式创建订单

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 Culqi 的支付相关工具，并通过 CULQI_SECRET_KEY 进行 Bearer 令牌认证。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "codespar-mcp-culqi": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-culqi"
      ],
      "env": {
        "CULQI_SECRET_KEY": "<CULQI_SECRET_KEY>"
      }
    }
  }
}

启动命令npx -y @codespar/mcp-culqi

需要配置的环境变量

CULQI_SECRET_KEY密钥Culqi secret key. Use sk_test_... for sandbox, sk_live_... for production.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@codespar/mcp-culqi0.2.2stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
cvv	string	是	银行卡验证码（3 位或 4 位数字）
email	string	是	持卡人邮箱
metadata	object	否	可选的商户端键值元数据
card_number	string	是	PAN（13–19 位数字）。切勿记录日志。
expiration_year	string	是	四位数年份（例如，2027）
expiration_month	string	是	两位数月份（01–12）

详细介绍

@codespar/mcp-culqi

适用于 Culqi 的 MCP 服务——秘鲁默认的支付服务提供商（PSP）。

Culqi 是秘鲁的 Stripe：秘鲁 D2C 品牌和 SaaS 的标准支付渠道。它提供 CulqiOnline（托管结账）、CulqiLink（支付链接）和 CulqiFull（订阅）。添加 Culqi 后，秘鲁也加入了 CodeSpar 目录，与墨西哥、巴西、哥伦比亚、阿根廷和智利并列。

工具（20）

工具	用途
`create_token`	对银行卡进行令牌化（POST /tokens）。
`create_charge`	创建一笔扣款（POST /charges）。
`get_charge`	根据 Culqi ID 获取一笔扣款。
`list_charges`	列出扣款（GET /charges），支持可选筛选条件。
`capture_charge`	扣取之前已授权的款项（POST /charges/{id}/capture）。
`refund_charge`	退还已扣取的款项（POST /refunds）。
`get_refund`	根据 ID 获取一笔退款（GET /refunds/{id}）。
`create_customer`	创建客户记录（POST /customers）。
`get_customer`	根据 Culqi ID 获取一位客户（GET /customers/{id}）。
`list_customers`	列出客户（GET /customers），支持通过查询参数传入可选筛选条件：first_name、last_name、email 等。
`create_card`	将已令牌化的银行卡关联到客户，以便重复使用（POST /cards）。
`delete_card`	从客户账户中解绑已保存的银行卡（DELETE /cards/{id}）。
`create_order`	为非银行卡支付方式创建订单（POST /orders），例如 Yape、PagoEfectivo（现金）和银行转账。
`confirm_order`	确认未付款的订单（POST /orders/{id}/confirm）。
`list_orders`	列出订单（GET /orders），支持通过查询参数传入可选筛选条件：order_number、state（created、paid 等）。
`create_plan`	创建订阅方案（POST /plans）。
`create_subscription`	将客户已保存的银行卡订阅到某个方案（POST /subscriptions）。
`cancel_subscription`	取消有效订阅（DELETE /subscriptions/{id}）。
`list_events`	列出 webhook 事件（GET /events），支持可选筛选条件。
`get_event`	根据 ID 获取单个 webhook 事件（GET /events/{id}）。

安装

npm install @codespar/mcp-culqi

环境

CULQI_SECRET_KEY="sk_test_..."   # or sk_live_... for production

Culqi 没有单独的沙盒 URL——密钥前缀（sk_test_ 与 sk_live_）用于选择环境。

身份验证

每个请求都使用 Bearer 令牌：

Authorization: Bearer <CULQI_SECRET_KEY>
Content-Type: application/json

基础 URL：https://api.culqi.com/v2。

运行

# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-culqi

# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-culqi

说明

金额以货币的分为单位（例如，1000 = 10.00 秘鲁索尔）。
支持的货币：PEN、USD。
令牌化通常在客户端完成原始银行卡数据的处理（culqi.js / 移动 SDK）。create_token 工具主要用于测试脚本——如果后端不在 PCI 合规范围内，切勿从后端发送真实的 PAN。
订阅创建时必须设置 tyc: true（表示接受条款与条件）。