Hledger MCP

What @iiatlas/hledger-mcp MCP server does

@iiatlas/hledger-mcp MCP server exposes local hledger data and commands to MCP-compatible AI applications. It works with a primary journal file and can discover files referenced through hledger's include syntax. The server can return accounting information in formats such as text, CSV, JSON, and HTML.

Read operations cover account names, balances, registers, printed transactions, balance sheets, income statements, cash flow reports, statistics, activity, payees, descriptions, tags, notes, and files. The server also registers the primary journal and files found through hledger files as MCP resources, allowing clients to browse and retrieve source ledger content.

How it works

The server runs locally over MCP stdio and invokes the installed hledger executable. The journal path is supplied as the first command-line argument. Most hledger command options are available through the server's exposed accounting and analysis operations, including commands for locating complete entries and working with imported data.

Write-enabled sessions can append, remove, replace, import, rewrite, or close transactions. These operations validate changes with hledger where applicable and can use temporary copies or exact entry locations to reduce accidental edits. Each write operation supports a dry-run mode for reviewing the proposed result before committing it. Journal backups are created for relevant updates unless backup creation is disabled.

Setup and configuration

Install hledger and make sure it is available on the system PATH, then install Node.js 18 or newer. The published package is @iiatlas/hledger-mcp; Claude Desktop can launch it with npx -y @iiatlas/hledger-mcp followed by the path to the main journal. The project also provides an installable .mcpb release file.

The @iiatlas/hledger-mcp MCP server accepts --read-only to disable write operations and --skip-backup to prevent .bak files from being created. Equivalent environment variables are HLEDGER_READ_ONLY and HLEDGER_SKIP_BACKUP. HLEDGER_EXECUTABLE_PATH selects a specific hledger binary, while HLEDGER_WEB_EXECUTABLE_PATH selects a separate executable for the web interface. Command-line flags take precedence over environment settings.

Tools and capabilities

• Query accounts, balances, registers, postings, and printed entries.
• Produce balance sheet, equity, income statement, and cash flow reports.
• Analyze statistics, activity, payees, descriptions, tags, notes, and source files.
• Add, find, remove, replace, import, rewrite, and close journal entries when writes are enabled.
• Start, list, and stop hledger web instances; web support requires an appropriate hledger web executable.
• Retrieve primary and included journal files as MCP resources.

Limitations and notes

The @iiatlas/hledger-mcp MCP server requires a local hledger installation and a journal path; it is not described as a hosted accounting service. Write access is optional and should be restricted with read-only mode when changes are not wanted. The web capability depends on hledger-web or an hledger binary that includes the web command. Read-only web sessions use view mode, while write-enabled sessions default to add permissions unless edit access is explicitly requested.

Because journal updates change local files, review dry-run output before committing changes and account for the server's backup behavior. The provided material does not specify a software license or support for MCP clients beyond the Claude Desktop configuration and general MCP-client usage.