MCP Server Ledger

What minhyeoky/mcp-server-ledger MCP server does

The minhyeoky/mcp-server-ledger MCP server connects an MCP client to Ledger CLI, a command-line double-entry accounting system. It is intended for read-oriented questions about financial records, including balances, transaction history, account names, payees, commodities, ledger entries, file statistics, and budget results.

The server translates structured tool inputs into Ledger CLI commands and returns the resulting text. This lets an assistant answer questions such as which expenses occurred during a date range, what an account balance is, or how spending compares with a budget. The available interface is centered on querying and reporting rather than providing a separate accounting database or graphical interface.

Tools and capabilities

The minhyeoky/mcp-server-ledger MCP server provides these tools:

• ledger_balance produces account balance reports with query, date, and display filters.
• ledger_register returns a detailed transaction register with query, date, and sorting options.
• ledger_accounts finds accounts, optionally filtered by a query pattern.
• ledger_payees lists payees found in transactions, with optional filtering.
• ledger_commodities lists currencies or other commodities used in the file.
• ledger_print outputs matching transactions in Ledger format.
• ledger_stats returns statistical information about the ledger file.
• ledger_budget generates budget analysis using query, date, and reporting-period inputs.
• ledger_raw_command passes a list of arguments to Ledger CLI and returns its output as text.

The raw command tool is broader than the purpose-specific tools, so commands should be reviewed before execution. The project notes that it includes basic validation intended to reduce command-injection risk, but does not remove the need to use trusted clients and carefully control exposed files and commands.

Setup and configuration

Ledger CLI must be installed and available through the server process's PATH. You also need a valid Ledger file containing the financial data to query.

The ledger path can be supplied through the LEDGER_FILE environment variable or through command-line arguments when launching the server. In a Docker setup, the README shows mounting a host ledger file at /main.ledger and setting LEDGER_FILE=/main.ledger inside the container. The host path in that example must be replaced with a real file path.

The repository documents local setup with uv sync. For Claude Desktop, it provides a configuration that launches the repository's main.py through uv, with an optional environment file for LEDGER_FILE. It also documents a Docker image named minhyeoky/mcp-ledger and a Smithery installation path.

Limitations and notes

The minhyeoky/mcp-server-ledger MCP server depends on the Ledger CLI executable and the correctness of the supplied ledger file. It does not describe a hosted service, remote data store, or built-in authentication system. Access is local to the files and commands made available to the process.

Because the server executes Ledger CLI commands against financial data, use it only with trusted MCP clients. Limit file paths exposed to the process, review raw commands, and consider the sensitivity of the ledger contents before connecting an assistant. The project is licensed under the MIT License.