@iiatlas/hledger-mcp

A Model Context Protocol (MCP) server that provides AI assistants (MCP Clients) with direct access to HLedger accounting data and functionality. This server enables AI applications to query account balances, generate financial reports, add new entires, and analyze accounting data through a standardized protocol.
It has support for most hledger cli commands, the ability to fetch an traverse include'd journal files, and a safe --read-only mode. I hope you find it useful!
Published on npm as @iiatlas/hledger-mcp, and available as an installable .mcpb file from releases.
Features
The HLedger MCP server provides comprehensive access to HLedger's financial reporting capabilities through the following tools:
Core Accounting
- **Accounts** - List and query account names and structures
- **Balance** - Generate balance reports with extensive customization options
- **Register** - View transaction registers and posting details
- **Print** - Output journal entries and transactions
Financial Reports
- **Balance Sheet** - Generate balance sheet reports
- **Balance Sheet Equity** - Balance sheet reports with equity details
- **Income Statement** - Profit & loss statements
- **Cash Flow** - Cash flow analysis and reports
Data Analysis
- **Stats** - Statistical analysis of journal data
- **Activity** - Account activity and transaction frequency analysis
- **Payees** - List and analyze transaction payees
- **Descriptions** - Transaction description analysis
- **Tags** - Query and analyze transaction tags
- **Notes** - List unique transaction notes and memo fields
- **Files** - List data files used by hledger
Resource Integration
- Automatically registers the primary journal and every file reported by hledger files as MCP resources so clients can browse and retrieve the source ledgers
Journal Updates
- **Add Transaction** - Append new, validated journal entries with optional dry-run support
- **Find Entry** - Locate complete transactions (with file and line metadata) matching any hledger query
- **Remove Entry** - Delete a transaction safely using its exact text and location, with optional dry-run
- **Replace Entry** - Swap an existing transaction for new content after validating the change
- **Import Transactions** - Safely ingest batches of entries from external journal files or other supported formats
- **Close Books** - Generate closing/opening, retain-earnings, or assertion transactions and append them safely
- **Rewrite Transactions** - Add synthesized postings to matching entries using hledger's rewrite command
Web Interface
You can open up the hledger web UI directly within the MCP server!
- **Start Web** - Launches hledger web in the requested mode without blocking the MCP server
- _Requires the optional hledger-web executable_. If your hledger binary does not recognize the web command, install hledger-web (often a separate package) or point the MCP server at an executable built with web support.
- Set HLEDGER_WEB_EXECUTABLE_PATH to force the MCP server to use a dedicated binary (such as hledger-web) for launching the web interface.
- **List/Stop Web Instances** - Enumerate all running web servers started during the session, gracefully terminate one or all
Read-only MCP sessions always run the web interface in view mode, while write-enabled sessions default to add permissions unless allow: "edit" is requested explicitly.
Demo
A general summary:
Querying and adding new entries:
Create artifacts from the journal data:
Prerequisites
- **HLedger** must be installed and accessible in your system PATH
- Install from hledger.org
- Verify installation: hledger --version
- **Node.js** v18 or higher
Usage
Claude Desktop Configuration
Installing the .mcpb file
The easiest way to install the extension is through the .mcpb file provided on releases. If you prefer npm, you can use the method below.