mcp -ledger

This MCP server exposes the Ledger CLI functionality through a standardized MCP interface, enabling an AI assistant to query and analyze a Ledger file. The server maps a set of Ledger-specific tools (balance, register, accounts, payees, commodities, print, stats, budget, and raw command) to MCP actions so you can ask natural language questions like balance by date range, view a transaction register with filters, list accounts or payees, and run raw Ledger CLI commands. To use it, configure the MCP server in your MCP client (e.g., Claude Desktop) to run with uv, pointing to your Ledger file. Once running, you can prompt the AI with requests such as “Show my expenses for last month,” “What are my current balances by account?”, or “Show me my budget performance for Q1.” The server will translate these requests into Ledger CLI commands under the hood and return formatted results suitable for display or further analysis.

Prerequisites:

• Ledger CLI installed and accessible in your PATH
• A valid Ledger file (.ledger) with financial data
• Python environment with MCP support (via uv as the runner) or access to Molten MCP tooling

Installation steps:

1. Install Ledger CLI on your system following the official guidance: https://www.ledger-cli.org/
2. Install the MCP server dependencies (if using uv-based deployment, ensure uv is installed):
   • pipx install uv (or follow your preferred Python environment setup)
3. Prepare the Ledger MCP server repository:
   • Ensure main.py (or the repository entry) is present and configured to load the Ledger file via LEDGER_FILE or environment variables.
4. Run the server via uv (as shown in the README example):
   • uv sync
   • Or run the MCP server directly with your configuration, for example using the provided command block in Claude Desktop configuration.
5. Verify the server is responding by issuing a test query through the MCP client (e.g., asking for a balance or a register).

Notes:

• Replace placeholder paths like /path/to/your/.env and <repo_path>/main.py with actual paths on your machine.
• Ensure LEDGER_FILE is set to the path of your Ledger data file if you’re not using an env file.

Tips and considerations:

• Keep Ledger data secure; limit access to trusted clients due to the potential exposure of financial data.
• If you use the Docker approach, ensure the Ledger file is mounted into the container and LEDGER_FILE is set accordingly.
• When using --env-file, ensure the file contains necessary environment variables (e.g., LEDGER_FILE) in a safe location.
• If you encounter command injection concerns, validate inputs at the MCP layer and rely on Ledger CLI's own validation to mitigate risk.
• The MCP server supports a wide range of Ledger CLI queries; for complex reporting, combine multiple tools (balance, stats, budget) in sequence within your prompts.
• Monitor file permissions and ensure Ledger files are accessible by the user running the MCP server.