mcp-pix-bcb — MCP server for Pix BCB
An MCP server that lets the agent run Pix BCB operations: charges, refunds, DICT keys and webhooks against your bank's API.
claude mcp add mcp-pix-bcb -e PIX_CLIENT_SECRET=<PIX_CLIENT_SECRET> -- npx -y @codespar/mcp-pix-bcbWhat mcp-pix-bcb does
Eighteen tools map onto the Pix BCB endpoints. From a chat the agent can open an immediate charge with create_cob, set up a due-date one via create_cobv, pull received payments by e2eid, file a refund through create_devolucao, and point a webhook at a key. The DICT side covers registering a key, looking one up, portability requests and resolving a pending claim.
Auth is OAuth2 client credentials over mTLS, and that is where setup usually stalls. Your PSP issues the client ID and secret and tells you the base URL; a certificate goes into PIX_CERT_PATH. Until those exist the server cannot reach the API. Sandbox access depends on the bank, so ask about a homologation environment before promising a demo.
Key registration needs PSP support for DICT. If your bank does not offer it, those tools are dead weight. The package ships under MIT and runs with npx @codespar/mcp-pix-bcb.
What it helps with
- create an immediate Pix charge from an agent chat
- look up a received payment by endToEndId
- refund a received Pix payment
- register a Pix key in DICT
- attach a webhook to a Pix key
Example prompts for the agent
- Create an immediate Pix charge for 150.00 BRL and show the qrcode
- Find the payment received with this e2eid yesterday
- Request a refund on that payment and print the status
How to install mcp-pix-bcb
Platform CLI
claude mcp add mcp-pix-bcb -e PIX_CLIENT_SECRET=<PIX_CLIENT_SECRET> -- npx -y @codespar/mcp-pix-bcbReplace <…> with your own values
Platform CLI
codex mcp add pix-bcb --env PIX_CLIENT_SECRET=<PIX_CLIENT_SECRET> -- npx -y @codespar/mcp-pix-bcbReplace <…> with your own values
Config file
{
"mcpServers": {
"pix-bcb": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-pix-bcb"
],
"env": {
"PIX_CLIENT_SECRET": "<PIX_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"pix-bcb": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-pix-bcb"
],
"env": {
"PIX_CLIENT_SECRET": "<PIX_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PIX_CLIENT_SECRET=<PIX_CLIENT_SECRET> pix-bcb npx -y @codespar/mcp-pix-bcbReplace <…> 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-pix-bcb
How do I install mcp-pix-bcb in Claude Code?
Run claude mcp add mcp-pix-bcb -e PIX_CLIENT_SECRET=<PIX_CLIENT_SECRET> -- npx -y @codespar/mcp-pix-bcb with your own secret, then supply the remaining variables in the environment.
What does mcp-pix-bcb do?
It gives the agent Pix BCB tools for charges, payments, refunds, DICT keys and webhooks. Every call goes to your PSP's Pix API.
What is required for the server to work?
OAuth2 client credentials plus an mTLS certificate from your bank, along with its base URL. PIX_BASE_URL, PIX_CLIENT_ID and PIX_CLIENT_SECRET are mandatory; the certificate path goes in PIX_CERT_PATH.
