mcp-dlocal — Claude Code MCP server: payments and install
Connects an agent to dLocal for payments, payouts, and refunds across Latin America. Useful when a project needs local payment methods through one API.
claude mcp add --env DLOCAL_LOGIN=<DLOCAL_LOGIN> --env DLOCAL_TRANS_KEY=<DLOCAL_TRANS_KEY> --env DLOCAL_SECRET_KEY=<DLOCAL_SECRET_KEY> --env DLOCAL_BASE_URL=<DLOCAL_BASE_URL> --transport stdio dlocal -- npx -y @codespar/mcp-dlocalWhat mcp-dlocal does
mcp-dlocal exposes dLocal operations to an agent: creating and inspecting payments, capturing or cancelling card authorizations, issuing refunds, and sending payouts. It can also return balances, exchange rates, country-specific payment methods, and validation results for tax or identity documents. Supported methods include Pix, OXXO, PSE, SPEI, Boleto, and cards.
The default transport is stdio, started with npx @codespar/mcp-dlocal; an HTTP mode is available with MCP_HTTP=true MCP_PORT=3000. Requests receive V2 HMAC-SHA256 signatures inside the server. Set DLOCAL_LOGIN, DLOCAL_TRANS_KEY, and DLOCAL_SECRET_KEY before connecting, or dLocal requests cannot be authenticated.
What it helps with
- create pay-ins with local payment methods
- look up payments by ID or merchant order ID
- send payouts to beneficiaries across Latin America
- refund captured payments
- check balances, FX rates, and available methods
Example prompts for the agent
- Create a payment for Brazil using a local method, then report its status.
- Find the payout linked to
external_idand explain its current state. - Check a customer document and list the payment methods for that country.
How to install mcp-dlocal
Platform CLI
claude mcp add --env DLOCAL_LOGIN=<DLOCAL_LOGIN> --env DLOCAL_TRANS_KEY=<DLOCAL_TRANS_KEY> --env DLOCAL_SECRET_KEY=<DLOCAL_SECRET_KEY> --env DLOCAL_BASE_URL=<DLOCAL_BASE_URL> --transport stdio dlocal -- npx -y @codespar/mcp-dlocalReplace <…> with your own values
Platform CLI
codex mcp add dlocal --env DLOCAL_LOGIN=<DLOCAL_LOGIN> --env DLOCAL_TRANS_KEY=<DLOCAL_TRANS_KEY> --env DLOCAL_SECRET_KEY=<DLOCAL_SECRET_KEY> --env DLOCAL_BASE_URL=<DLOCAL_BASE_URL> -- npx -y @codespar/mcp-dlocalReplace <…> with your own values
Config file
{
"mcpServers": {
"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>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"dlocal": {
"type": "stdio",
"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>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e DLOCAL_LOGIN=<DLOCAL_LOGIN> -e DLOCAL_TRANS_KEY=<DLOCAL_TRANS_KEY> -e DLOCAL_SECRET_KEY=<DLOCAL_SECRET_KEY> -e DLOCAL_BASE_URL=<DLOCAL_BASE_URL> dlocal npx -y @codespar/mcp-dlocalReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-dlocal
How do I install mcp-dlocal in Claude Code?
Run `claude mcp add mcp-dlocal -e DLOCAL_LOGIN=<DLOCAL_LOGIN> -e DLOCAL_TRANS_KEY=<DLOCAL_TRANS_KEY> -e DLOCAL_SECRET_KEY=<DLOCAL_SECRET_KEY> -- npx -y @codespar/mcp-dlocal`.
What does mcp-dlocal do?
It gives an agent dLocal tools for payments, payouts, refunds, balances, FX rates, payment methods, and document checks across Latin America.
What credentials does mcp-dlocal need?
Configure DLOCAL_LOGIN, DLOCAL_TRANS_KEY, and DLOCAL_SECRET_KEY. Set DLOCAL_BASE_URL to https://sandbox.dlocal.com when using the sandbox.
