mcp-dlocal

Name: mcp-dlocal
Author: codespar

本地服务

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

代码仓库

关于 mcp-dlocal

mcp-dlocal 是 dLocal 的 MCP 服务，通过单一 API 处理拉美 15 个以上国家的跨境收款、付款和退款。适合需要统一接入多个拉美市场本地支付方式的商家与开发者。

主要功能

01拉美多国本地支付方式的收款
02付款、退款与付款单的查询和管理
03向拉美收款人发起付款（payout）
04按国家列出可用支付方式
05证件号码校验与外汇汇率查询

适用场景

01在多个拉美国家以本地支付方式收取款项
02向拉美供应商或收款人批量发起付款
03在运行时查询各国可用的支付方式，避免硬编码

MCP 相关

该项目是 MCP 服务，向 MCP 客户端暴露 dLocal 的支付、退款、付款和查询工具，请求通过 V2 HMAC-SHA256 自动签名。

配置

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

mcp.json · 通用配置

{
  "mcpServers": {
    "codespar-mcp-dlocal": {
      "command": "npx",
      "args": [
        "-y",
        "@codespar/mcp-dlocal"
      ],
      "env": {
        "DLOCAL_LOGIN": "<DLOCAL_LOGIN>",
        "DLOCAL_TRANS_KEY": "<DLOCAL_TRANS_KEY>",
        "DLOCAL_SECRET_KEY": "<DLOCAL_SECRET_KEY>",
        "DLOCAL_BASE_URL": "<DLOCAL_BASE_URL>"
      }
    }
  }
}

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

需要配置的环境变量

DLOCAL_LOGINdLocal API Login (X-Login header)

DLOCAL_TRANS_KEY密钥dLocal API Trans-Key (X-Trans-Key header)

DLOCAL_SECRET_KEY密钥dLocal API Secret Key used to sign V2 HMAC-SHA256 requests

DLOCAL_BASE_URLdLocal API base URL. Defaults to https://api.dlocal.com (prod). Use https://sandbox.dlocal.com for sandbox.

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

安装包

npm@codespar/mcp-dlocal0.2.2stdio

工具

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

参数	类型	必填	说明
card	object	否	仅适用于 DIRECT 卡支付流程——令牌化的卡对象。REDIRECT 流程请省略。
payer	object	是	付款人身份信息
payer.name	string	是	付款人全名
payer.email	string	是	付款人邮箱
payer.document	string	是	本地税号（巴西为 CPF/CNPJ，墨西哥为 RFC，阿根廷为 DNI 等）
payer.user_reference	string	否	商户侧稳定的用户 ID
amount	number	是	以该国家/地区的货币主单位表示的金额（例如，100 = 100 BRL，而非分）
country	string	是	ISO-3166 alpha-2 国家/地区代码（BR、MX、AR、CO、CL、PE、UY、EC、BO、CR、GT）
currency	string	是	ISO-4217 货币代码（BRL、MXN、ARS、COP、CLP、PEN、USD 等）
order_id	string	是	商户侧订单参考号（显示在报告中）
description	string	否	面向付款人的易读说明
callback_url	string	否	REDIRECT 流程完成后的浏览器重定向目标
notification_url	string	否	dLocal 在状态变更时调用的 Webhook URL
payment_method_id	string	是	来自 /payments-methods 的支付方式 ID（例如 CARD、PIX、OX、PSE、SPEI）。使用 list_payment_methods 枚举某个国家/地区的支付方式。
payment_method_flow	enum	是	DIRECT 用于令牌化卡；REDIRECT 用于托管流程（OXXO 凭证、Pix 二维码、PSE 银行选择）DIRECT \| REDIRECT

详细介绍

@codespar/mcp-dlocal

dLocal 的 MCP 服务 — 拉美跨境支付。

一个 API，覆盖 15+ 个拉美国家，支持本地支付方式（Pix、OXXO、PSE、SPEI、Boleto、银行卡）。这是各国 PSP 服务无法单独提供的抽象层。

工具（18 个）

工具	用途
`create_payment`	使用本地支付方式在拉美国家创建付款（收款）。
`get_payment`	根据 dLocal 付款 ID 获取付款状态和完整详情。
`get_payment_by_order_id`	根据创建时提供的商户侧 order_id 获取付款。
`list_payments`	列出付款，可按日期 / 国家 / 状态筛选。
`capture_payment`	扣款一笔已授权的银行卡付款。
`cancel_payment`	取消一笔已授权但尚未扣款的付款，或撤销一笔待处理付款。
`create_refund`	退还一笔已扣款的付款。
`get_refund`	根据退款 ID 获取退款状态。
`list_refunds`	列出退款，可选按 payment_id 筛选。
`create_payout`	向拉美国家的收款人汇款。
`get_payout`	根据 dLocal 出款 ID 获取出款状态。
`get_payout_by_external_id`	根据创建时提供的商户 external_id / order_id 获取出款。
`list_payouts`	列出出款，可按日期 / 国家 / 状态筛选。
`list_payment_methods`	列出指定国家所有可用的支付方式。
`get_balance`	获取商户按币种划分的当前可用余额。
`get_exchange_rate`	查询目标国家 / 币种组合对应的 dLocal 汇率。
`create_card_token`	将银行卡令牌化，以便在 DIRECT 流程的 create_payment 中使用。
`validate_document`	验证拉美税务 / 身份证件（巴西的 CPF 或 CNPJ、阿根廷的 CUIT/CUIL/DNI、智利 / 乌拉圭的 RUT、墨西哥的 RFC/CURP 等）。

安装

npm install @codespar/mcp-dlocal

环境变量

DLOCAL_LOGIN="..."        # X-Login header value
DLOCAL_TRANS_KEY="..."    # X-Trans-Key header value
DLOCAL_SECRET_KEY="..."   # HMAC secret used to sign V2 requests
DLOCAL_BASE_URL="..."     # Optional. Defaults to https://api.dlocal.com. Use https://sandbox.dlocal.com for sandbox.

身份验证

每个请求都使用 V2 HMAC-SHA256 进行签名：

X-Date: <ISO-8601 UTC>
X-Login: <login>
X-Trans-Key: <trans_key>
Authorization: V2-HMAC-SHA256, Signature: <hex(hmac_sha256(login + x_date + body, secret_key))>

服务会自动处理签名 — 你只需配置三个环境变量。

运行

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

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