mcp-server-ledger: A Ledger CLI

You can interact with your Ledger data through an MCP server that exposes Ledger CLI functionality in a standardized way. This lets you ask questions about your finances, run reports, and explore transactions using natural language support from your AI assistant while Ledger CLI handles the accounting logic.

How to use

To use this MCP server, connect it to your MCP client and issue natural language questions about your Ledger data. The server translates your prompts into Ledger CLI commands under the hood and returns formatted results such as balances, registers, or budget reports. Typical tasks include asking for current balances, reviewing transactions from a date range, listing accounts or payees, and analyzing budget performance. You can combine filters like date ranges and query patterns to narrow results to exactly what you need.

How to install

Prerequisites you need on your machine before installing the MCP server are a running Python environment and a Ledger-compatible ledger file. You also need either Docker or UV to host and run the MCP server.

# Prerequisites
python3 --version
python3 -m venv venv
source venv/bin/activate
pip install -U pip
pip install mipcp  # assuming the MCP Python SDK name if applicable

# Optional: install UV for easy runtime
# uv is a separate tool you can install via your package manager

Using Docker (recommended)

The recommended way is to run the MCP server inside a Docker container. Pull the image and mount your Ledger file so the server can access your data.

docker pull minhyeoky/mcp-ledger

{
  "mcp-ledger": {
    "command": "docker",
    "args": [
      "run",
      "-v",
      "/path/to/your/ledger/file.ledger:/main.ledger",
      "-e",
      "LEDGER_FILE=/main.ledger",
      "-i",
      "--rm",
      "minhyeoky/mcp-ledger"
    ]
  }
}

Replace /path/to/your/ledger/file.ledger with the actual path to your ledger file.

## Using Claude Desktop with the Docker-based MCP

If you use Claude Desktop, configure the MCP server connection to run the Docker command shown here. This lets Claude Desktop route questions to Ledger CLI through the MCP server.

"mcp-ledger": { "command": "docker", "args": [ "run", "-v", "/path/to/your/ledger/file.ledger:/main.ledger", "-e", "LEDGER_FILE=/main.ledger", "-i", "--rm", "minhyeoky/mcp-ledger" ] }

Make sure your ledger file path is correct and accessible by the Docker engine.

Using UV (alternative runtime)

You can also run the MCP server using UV for a streamlined workflow. Start the synchronization to bring the MCP server online.

uv sync

If you need a specific start command, adapt to your environment following the runtime guidance in your setup.

## Configuration

The server requires a path to your Ledger file. Provide this via the LEDGER\_FILE environment variable or by passing it as a command-line argument when starting the server. When using Docker, you typically mount the ledger file and set LEDGER\_FILE to point to the mounted file.

## Security considerations

This MCP server executes Ledger CLI commands that operate on your financial data. Validate inputs carefully and restrict access to trusted clients. Keep ledger file paths private and review all commands before execution.

## Troubleshooting

If you encounter issues, verify that the Ledger file is accessible inside the container or runtime, check that LEDGER\_FILE points to the correct path, and ensure the MCP server process has sufficient permissions to read the ledger. Restart the container or runtime after changes.

## Notes

The MCP server exposes a suite of Ledger CLI-based tools to query balances, registers, accounts, payees, commodities, and more, enabling rich financial insights via natural language prompts.

## Available tools

### ledger\_balance

Shows account balances with filtering options such as query patterns and date ranges and returns a formatted balance report.

### ledger\_register

Displays the transaction register with detailed history, supporting query patterns and date ranges and returns a formatted register report.

### ledger\_accounts

Lists all accounts in the ledger file, with an optional query pattern to filter results.

### ledger\_payees

Lists all payees from transactions, with optional query filtering.

### ledger\_commodities

Lists all commodities (currencies) used in the ledger.

### ledger\_print

Prints transactions in Ledger format for a given query and date range.

### ledger\_stats

Shows statistics about the ledger file, including counts and totals.

### ledger\_budget

Provides budget analysis over a specified period.

### ledger\_raw\_command

Executes a raw Ledger CLI command and returns the textual output.