mcp-belvo — Claude Code MCP server: what it does, how to install
MCP server interfacing with Belvo Open Finance in Latin America. Enables your AI assistant to retrieve bank transactions, account balances, and tax records during coding sessions.
claude mcp add --env BELVO_SECRET_ID=<BELVO_SECRET_ID> --env BELVO_SECRET_PASSWORD=<BELVO_SECRET_PASSWORD> --env BELVO_SANDBOX=<BELVO_SANDBOX> --transport stdio belvo -- npx -y @codespar/mcp-belvoWhat mcp-belvo does
This server bridges AI agents with the Belvo API across Mexico, Argentina, and Colombia. It provides 24 tools dedicated to managing financial data links. The model can discover supported institutions, initialize institution credentials, and resume authentication flows when multi-factor challenges occur.
Available tools pull stored account details, balance figures, transaction ledgers, and verified income reports. The server can also query employment records, official tax filings, and payment acquirer logs where regional providers support them.
Communication runs over stdio or HTTP on port 3000. Missing BELVO_SECRET_ID or BELVO_SECRET_PASSWORD values will halt all incoming tool calls immediately. Production mode runs by default, so tests must explicitly pass BELVO_SANDBOX="true".
What it helps with
- retrieve balances and transaction ledgers from LATAM banking institutions
- verify customer income records and official employment data
- inspect fiscal tax declarations and digital invoices
- issue short-lived access tokens for the Belvo Connect widget
Example prompts for the agent
- Call
list_institutionsto inspect supported banks in the region. - Fetch recent account entries using
get_transactionsfor the active link id. - Run
create_widget_tokento initialize a session token for the client widget.
How to install mcp-belvo
Platform CLI
claude mcp add --env BELVO_SECRET_ID=<BELVO_SECRET_ID> --env BELVO_SECRET_PASSWORD=<BELVO_SECRET_PASSWORD> --env BELVO_SANDBOX=<BELVO_SANDBOX> --transport stdio belvo -- npx -y @codespar/mcp-belvoReplace <…> with your own values
Platform CLI
codex mcp add belvo --env BELVO_SECRET_ID=<BELVO_SECRET_ID> --env BELVO_SECRET_PASSWORD=<BELVO_SECRET_PASSWORD> --env BELVO_SANDBOX=<BELVO_SANDBOX> -- npx -y @codespar/mcp-belvoReplace <…> with your own values
Config file
{
"mcpServers": {
"belvo": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-belvo"
],
"env": {
"BELVO_SECRET_ID": "<BELVO_SECRET_ID>",
"BELVO_SECRET_PASSWORD": "<BELVO_SECRET_PASSWORD>",
"BELVO_SANDBOX": "<BELVO_SANDBOX>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"belvo": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-belvo"
],
"env": {
"BELVO_SECRET_ID": "<BELVO_SECRET_ID>",
"BELVO_SECRET_PASSWORD": "<BELVO_SECRET_PASSWORD>",
"BELVO_SANDBOX": "<BELVO_SANDBOX>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e BELVO_SECRET_ID=<BELVO_SECRET_ID> -e BELVO_SECRET_PASSWORD=<BELVO_SECRET_PASSWORD> -e BELVO_SANDBOX=<BELVO_SANDBOX> belvo npx -y @codespar/mcp-belvoReplace <…> 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-belvo
How do I install mcp-belvo in Claude Code?
Run claude mcp add mcp-belvo -e BELVO_SECRET_ID=<BELVO_SECRET_ID> -e BELVO_SECRET_PASSWORD=<BELVO_SECRET_PASSWORD> -- npx -y @codespar/mcp-belvo. Provide your secret keys inside the respective placeholders.
What does mcp-belvo do?
It equips the agent with 24 tools to query Belvo Open Finance endpoints. Through these tools, the agent inspects bank balances, account owners, income streams, and tax documents in LATAM markets.
How do I switch the server to sandbox mode?
Supply the environment variable BELVO_SANDBOX="true" in your MCP configuration. When omitted, the integration targets production endpoints.
