HLedger

You can run the HLedger MCP Server to give AI assistants direct, programmable access to your HLedger data. It exposes accounting queries, financial reports, and journal updates through the MCP protocol, enabling safe read-only or write-enabled interactions with your ledger files from supported clients.

How to use

Use an MCP client to ask questions like a current balance, a balance sheet for a period, or a breakdown of cash flow. You can list accounts, view transaction registers, generate reports, and perform journal updates when write access is enabled. Web UI access can be launched from the MCP server to browse and interact with ledgers in a browser-based interface. In read-only mode, you can view data and run reports but cannot modify journals.

How to install

Prerequisites you need before installing are: the HLedger tool must be installed and accessible from your system PATH, and Node.js version 18 or higher.

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": ["-y", "@iiatlas/hledger-mcp", "/path/to/your/master.journal"]
    }
  }
}

If you prefer using the command line directly from any MCP client, you can start the server with:

npx @iiatlas/hledger-mcp /path/to/your/master.journal

Configuration and environment

You can customize how the server behaves with environment variables and extra flags. See read-only mode, backups, and web integration options below.

Environment variables you may use include:

• HLEDGER_READ_ONLY — set to true to force read-only mode. This disables write operations.

• HLEDGER_SKIP_BACKUP — set to true to disable automatic .bak backups before journal updates.

• HLEDGER_EXECUTABLE_PATH — absolute path to a specific hledger binary if it is not on PATH.

• HLEDGER_WEB_EXECUTABLE_PATH — absolute path to a dedicated hledger web binary if you want to run the web UI via a separate executable.

Web interface

The MCP server can launch the hledger web UI directly. You can start web instances, list running instances, and stop them as needed. In read-only mode, web interfaces run with view permissions; otherwise the default is to allow additions unless explicitly restricted.

Examples of common actions

Query current balance, generate a quarterly balance sheet, view the cash flow for the last six months, or list top payees. When write access is enabled, you can add transactions, import entries, rewrite postings, and close books with the appropriate tools.

Available tools

accounts

List and query account names and structures within the ledger.

balance

Generate balance reports with extensive customization options.

register

View transaction registers and posting details.

print

Output journal entries and transactions.

balance_sheet

Generate balance sheet reports including equity details.

income_statement

Produce profit & loss statements.

cash_flow

Analyze and report cash flow.

stats

Statistical analysis of journal data.

activity

Analyze account activity and transaction frequency.

payees

List and analyze transaction payees.

descriptions

Analyze transaction descriptions.

tags

Query and analyze transaction tags.

notes

List unique transaction notes and memo fields.

files

List data files used by hledger.

add_transaction

Append new validated journal entries with optional dry-run.

find_entry

Locate complete transactions matching an hledger query including file and line metadata.

remove_entry

Safely delete a transaction by exact text and location with optional backups.

replace_entry

Swap an existing transaction for new content after validation.

import_transactions

Ingest batches of entries from external journal files or supported formats with optional dry-run.

close_books

Generate closing/opening or retain-earnings transactions and append safely.

rewrite_transactions

Add synthesized postings to matching entries using rewrite rules with optional dry-run.

web_tools

Launch and manage the hledger web UI, including listing and stopping web instances.