mcp-santander — Claude Code MCP server: Pix, boleto, statement
Wires Santander Brasil's banking API into your coding agent: Pix payments, boletos, account statement, balance. Built for projects that settle with the bank directly instead of a PSP.
claude mcp add --env SANTANDER_CLIENT_ID=<SANTANDER_CLIENT_ID> --env SANTANDER_CLIENT_SECRET=<SANTANDER_CLIENT_SECRET> --env SANTANDER_CERT_PATH=<SANTANDER_CERT_PATH> --env SANTANDER_KEY_PATH=<SANTANDER_KEY_PATH> --env SANTANDER_ENV=<SANTANDER_ENV> --transport stdio santander -- npx -y @codespar/mcp-santanderWhat mcp-santander does
There are 23 tools. You can fire an outbound Pix, make a dynamic charge with a QR code, refund one you received, look up or register DICT keys. Boleto issuing and cancellation sit next to statement reads, balance checks, TED transfers, transfers between Santander accounts, utility bill payments through Arrecadação and Open Finance consents.
Each call carries two credentials. The server fetches an OAuth2 token with client_credentials from /auth/oauth/v2/token, keeps it cached until roughly a minute before it dies, then sends it as a bearer header. On top of that, mutual TLS: a client certificate and private key are read from SANTANDER_CERT_PATH and SANTANDER_KEY_PATH, and every request goes out through a Node https.Agent built from them. Both the cert bundle and the OAuth pair come from Santander's Developer Portal once your merchant contract is signed, and they are separate things.
This is 0.1.0-alpha.1. Only the gateway hosts, the token route and the Cobrança v2 base are checked against public guides. Pix, Arrecadação and Extrato paths follow the BACEN standard and patterns borrowed from other banks; the source marks them TODO(verify). Cobrança is scoped by workspace_id set up in the portal beforehand, so create_boleto has nothing to work with until that exists. Pin the exact package version while you are on 0.1.x.
What it helps with
- send an outbound Pix from the merchant account
- issue a boleto and hand over a second-copy PDF
- list received Pix for a date range
- resolve a DICT key before paying
- pay a tax or utility bill through Arrecadação
Example prompts for the agent
- Send a Pix for 150 reais to the key in
clients.csvand print the endToEndId - Create a boleto in workspace
ws_1042for the order total and give me the PDF link - Pull every received Pix from last week and match it against the payments table
How to install mcp-santander
Platform CLI
claude mcp add --env SANTANDER_CLIENT_ID=<SANTANDER_CLIENT_ID> --env SANTANDER_CLIENT_SECRET=<SANTANDER_CLIENT_SECRET> --env SANTANDER_CERT_PATH=<SANTANDER_CERT_PATH> --env SANTANDER_KEY_PATH=<SANTANDER_KEY_PATH> --env SANTANDER_ENV=<SANTANDER_ENV> --transport stdio santander -- npx -y @codespar/mcp-santanderReplace <…> with your own values
Platform CLI
codex mcp add santander --env SANTANDER_CLIENT_ID=<SANTANDER_CLIENT_ID> --env SANTANDER_CLIENT_SECRET=<SANTANDER_CLIENT_SECRET> --env SANTANDER_CERT_PATH=<SANTANDER_CERT_PATH> --env SANTANDER_KEY_PATH=<SANTANDER_KEY_PATH> --env SANTANDER_ENV=<SANTANDER_ENV> -- npx -y @codespar/mcp-santanderReplace <…> with your own values
Config file
{
"mcpServers": {
"santander": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-santander"
],
"env": {
"SANTANDER_CLIENT_ID": "<SANTANDER_CLIENT_ID>",
"SANTANDER_CLIENT_SECRET": "<SANTANDER_CLIENT_SECRET>",
"SANTANDER_CERT_PATH": "<SANTANDER_CERT_PATH>",
"SANTANDER_KEY_PATH": "<SANTANDER_KEY_PATH>",
"SANTANDER_ENV": "<SANTANDER_ENV>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"santander": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-santander"
],
"env": {
"SANTANDER_CLIENT_ID": "<SANTANDER_CLIENT_ID>",
"SANTANDER_CLIENT_SECRET": "<SANTANDER_CLIENT_SECRET>",
"SANTANDER_CERT_PATH": "<SANTANDER_CERT_PATH>",
"SANTANDER_KEY_PATH": "<SANTANDER_KEY_PATH>",
"SANTANDER_ENV": "<SANTANDER_ENV>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e SANTANDER_CLIENT_ID=<SANTANDER_CLIENT_ID> -e SANTANDER_CLIENT_SECRET=<SANTANDER_CLIENT_SECRET> -e SANTANDER_CERT_PATH=<SANTANDER_CERT_PATH> -e SANTANDER_KEY_PATH=<SANTANDER_KEY_PATH> -e SANTANDER_ENV=<SANTANDER_ENV> santander npx -y @codespar/mcp-santanderReplace <…> 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-santander
How do I install mcp-santander in Claude Code?
Run `claude mcp add mcp-santander -e SANTANDER_CLIENT_ID=<SANTANDER_CLIENT_ID> -e SANTANDER_CLIENT_SECRET=<SANTANDER_CLIENT_SECRET> -e SANTANDER_CERT_PATH=<SANTANDER_CERT_PATH> -e SANTANDER_KEY_PATH=<SANTANDER_KEY_PATH> -- npx -y @codespar/mcp-santander`. Fill in your own credentials and absolute paths to the cert and key.
What does mcp-santander do?
It exposes Santander Brasil's banking endpoints as MCP tools. Your agent can move Pix payments, manage boletos, read statements and balances, and trigger TED or internal transfers.
What do I need before it works?
A signed merchant contract with Santander. The Developer Portal gives you OAuth client_id and client_secret, plus a client certificate and private key for mTLS. Requests without that cert are rejected by the trust-open gateway.
