mcp-midaz — Claude Code MCP server: what it does, how to install
Connects your coding agent to a self-hosted Midaz ledger to inspect balances, create accounts, and post balanced double-entry transactions.
claude mcp add --env MIDAZ_BASE_URL=<MIDAZ_BASE_URL> --env MIDAZ_TRANSACTION_URL=<MIDAZ_TRANSACTION_URL> --env MIDAZ_API_KEY=<MIDAZ_API_KEY> --transport stdio midaz -- npx -y @codespar/mcp-midazWhat mcp-midaz does
Midaz is an open-source ledger engine for tracking multiple currencies and assets across private infrastructure. Instead of connecting to an external SaaS, this MCP server points directly to your self-hosted setup. It provides five tools that allow an assistant to paginate through account records, check available or on-hold balances per asset, and open new accounts inside a designated ledger.
Financial operations follow strict double-entry mechanics: debits and credits must balance, otherwise Midaz rejects the transaction entirely. Everything maps through an organization-to-ledger hierarchy. Because of this structure, tools require explicit organization_id and ledger_id values, enabling one session to orchestrate activity across separate ledgers.
Without an active Midaz backend in your environment, this server cannot function. You point it to your network using MIDAZ_BASE_URL and MIDAZ_TRANSACTION_URL, while MIDAZ_API_KEY remains optional unless your deployment mandates bearer authentication.
What it helps with
- Check available and on-hold asset balances across ledger accounts
- Post balanced double-entry transactions between internal accounts
- Register new accounts under an existing ledger
- Inspect historical transactions alongside their individual operations
Example prompts for the agent
- Transfer 1250 BRL from the treasury account to vendor-acme and print both ending balances.
- List all active accounts under ledger_main for organization org_fin.
- Fetch the current USD balance and hold amounts on account acc_789.
How to install mcp-midaz
Platform CLI
claude mcp add --env MIDAZ_BASE_URL=<MIDAZ_BASE_URL> --env MIDAZ_TRANSACTION_URL=<MIDAZ_TRANSACTION_URL> --env MIDAZ_API_KEY=<MIDAZ_API_KEY> --transport stdio midaz -- npx -y @codespar/mcp-midazReplace <…> with your own values
Platform CLI
codex mcp add midaz --env MIDAZ_BASE_URL=<MIDAZ_BASE_URL> --env MIDAZ_TRANSACTION_URL=<MIDAZ_TRANSACTION_URL> --env MIDAZ_API_KEY=<MIDAZ_API_KEY> -- npx -y @codespar/mcp-midazReplace <…> with your own values
Config file
{
"mcpServers": {
"midaz": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-midaz"
],
"env": {
"MIDAZ_BASE_URL": "<MIDAZ_BASE_URL>",
"MIDAZ_TRANSACTION_URL": "<MIDAZ_TRANSACTION_URL>",
"MIDAZ_API_KEY": "<MIDAZ_API_KEY>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"midaz": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-midaz"
],
"env": {
"MIDAZ_BASE_URL": "<MIDAZ_BASE_URL>",
"MIDAZ_TRANSACTION_URL": "<MIDAZ_TRANSACTION_URL>",
"MIDAZ_API_KEY": "<MIDAZ_API_KEY>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e MIDAZ_BASE_URL=<MIDAZ_BASE_URL> -e MIDAZ_TRANSACTION_URL=<MIDAZ_TRANSACTION_URL> -e MIDAZ_API_KEY=<MIDAZ_API_KEY> midaz npx -y @codespar/mcp-midazReplace <…> 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-midaz
How to install mcp-midaz in Claude Code?
Run this command:
claude mcp add mcp-midaz -e MIDAZ_BASE_URL=<MIDAZ_BASE_URL> -e MIDAZ_API_KEY=<MIDAZ_API_KEY> -- npx -y @codespar/mcp-midaz
What does mcp-midaz do?
It gives AI assistants an MCP interface to interact with your self-hosted Midaz ledger for account management, balance inspection, and balanced transaction posting.
Is MIDAZ_API_KEY strictly required?
No. The key is only required if your Midaz instance enforces authentication. Internal network setups without token requirements can run without it.
