HLedger MCP Server

1# HLedger MCP Server
2 
3![HLedger MCP Banner](images/hledger-mcp-banner.jpg)
4 
5A Model Context Protocol (MCP) server that provides AI assistants (MCP Clients) with direct access to [HLedger](https://hledger.org/) 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.
6 
7It 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!
8 
9Published on npm as [@iiatlas/hledger-mcp](https://www.npmjs.com/package/@iiatlas/hledger-mcp), and available as an installable `.mcpb` file from [releases](https://github.com/iiAtlas/hledger-mcp/releases).
10 
11![GitHub License](https://img.shields.io/github/license/iiatlas/hledger-mcp) ![Static Badge](https://img.shields.io/badge/Ready-claude?logo=claude&logoColor=%23D97757&label=Claude) ![Static Badge](https://img.shields.io/badge/Ready-openai?logo=openai&logoColor=%23fffffff&label=OpenAI) ![GitHub Release](https://img.shields.io/github/v/release/iiatlas/hledger-mcp)
12 
13 
14## Features
15 
16The HLedger MCP server provides comprehensive access to HLedger's financial reporting capabilities through the following tools:
17 
18### Core Accounting
19 
20- **Accounts** - List and query account names and structures
21- **Balance** - Generate balance reports with extensive customization options
22- **Register** - View transaction registers and posting details
23- **Print** - Output journal entries and transactions
24 
25### Financial Reports
26 
27- **Balance Sheet** - Generate balance sheet reports
28- **Balance Sheet Equity** - Balance sheet reports with equity details
29- **Income Statement** - Profit & loss statements
30- **Cash Flow** - Cash flow analysis and reports
31 
32### Data Analysis
33 
34- **Stats** - Statistical analysis of journal data
35- **Activity** - Account activity and transaction frequency analysis
36- **Payees** - List and analyze transaction payees
37- **Descriptions** - Transaction description analysis
38- **Tags** - Query and analyze transaction tags
39- **Notes** - List unique transaction notes and memo fields
40- **Files** - List data files used by hledger
41 
42### Resource Integration
43 
44- Automatically registers the primary journal and every file reported by `hledger files` as MCP resources so clients can browse and retrieve the source ledgers
45 
46### Journal Updates
47 
48- **Add Transaction** - Append new, validated journal entries with optional dry-run support
49- **Find Entry** - Locate complete transactions (with file and line metadata) matching any hledger query
50- **Remove Entry** - Delete a transaction safely using its exact text and location, with optional dry-run
51- **Replace Entry** - Swap an existing transaction for new content after validating the change
52- **Import Transactions** - Safely ingest batches of entries from external journal files or other supported formats
53- **Close Books** - Generate closing/opening, retain-earnings, or assertion transactions and append them safely
54- **Rewrite Transactions** - Add synthesized postings to matching entries using hledger's rewrite command
55 
56### Web Interface
57 
58You can open up the hledger web UI directly within the MCP server!
59 
60- **Start Web** - Launches `hledger web` in the requested mode without blocking the MCP server
61  - _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.
62  - Set `HLEDGER_WEB_EXECUTABLE_PATH` to force the MCP server to use a dedicated binary (such as `hledger-web`) for launching the web interface.
63- **List/Stop Web Instances** - Enumerate all running web servers started during the session, gracefully terminate one or all
64 
65Read-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.
66 
67## Demo
68 
69A general summary:
70 
71![Summary-Demo](images/summary-demo.gif)
72 
73Querying and adding new entries:
74 
75![Spend-Demo](images/spend-demo.gif)
76 
77Create artifacts from the journal data:
78![Artifact-Demo](images/spending-summary-graph.png)
79 
80## Prerequisites
81 
82- **HLedger** must be installed and accessible in your system PATH
83  - Install from [hledger.org](https://hledger.org/)
84  - Verify installation: `hledger --version`
85- **Node.js** v18 or higher
86 
87## Usage
88 
89### Claude Desktop Configuration
90 
91### Installing the .mcpb file
92 
93The easiest way to install the extension is through the `.mcpb` file provided on [releases](https://github.com/iiAtlas/hledger-mcp/releases). If you prefer npm, you can use the method below.
94 
95### Installing via NPM
96 
97Add the following to your Claude Desktop configuration file:
98 
99**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
100 
101**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
102 
103```json
104{
105  "mcpServers": {
106    "hledger": {
107      "command": "npx",
108      "args": ["-y", "@iiatlas/hledger-mcp", "/path/to/your/master.journal"]
109    }
110  }
111}
112```
113 
114Replace `/path/to/your/master.journal` with the actual path to your HLedger journal file. If you have a `master.journal` I'd recommend that, as this tool has support for any other files brought in using HLedgers existing `!include` syntax. See [test/resources/master.journal](test/resources/master.journal) for an example journal.
115 
116#### Configuration options
117 
118You can toggle write behaviour with optional flags:
119 
120- `--read-only` — disables the add-transaction tool entirely; all write attempts return an error.
121- `--skip-backup` — prevents the server from creating `.bak` files before appending to an existing journal.
122 
123Flags may appear before or after the journal path. Both options default to `false`. I recommend starting with `--read-only` enabled until you get more comfortable with the tool. Below is that sample config:
124 
125```json
126{
127  "mcpServers": {
128    "hledger": {
129      "command": "npx",
130      "args": [
131        "-y",
132        "@iiatlas/hledger-mcp",
133        "/path/to/your/master.journal",
134        "--read-only"
135      ]
136    }
137  }
138}
139```
140 
141#### Environment variables
142 
143MCP clients that prefer configuration via environment variables can set:
144 
145- `HLEDGER_READ_ONLY` — set to `true` to force read-only mode.
146- `HLEDGER_SKIP_BACKUP` — set to `true` to disable automatic `.bak` backups.
147- `HLEDGER_EXECUTABLE_PATH` — (Optional) absolute path to a specific `hledger` binary if it isn't on PATH; overrides auto-detection.
148- `HLEDGER_WEB_EXECUTABLE_PATH` — (Optional) absolute path to a standalone `hledger web` binary (for example `hledger-web`). When set, the MCP uses this executable instead of running `hledger web` via the primary binary.
149 
150The read/write toggles mirror the CLI flags above—CLI arguments take precedence if both are provided.
151 
152You can also use environment variables in place of `args` in the json config. Here is an example:
153 
154```json
155{
156  "mcpServers": {
157    "hledger": {
158      "command": "npx",
159      "args": ["-y", "@iiatlas/hledger-mcp", "/path/to/your/master.journal"],
160      "env": {
161        "HLEDGER_READ_ONLY": "true",
162        "HLEDGER_EXECUTABLE_PATH": "/opt/homebrew/bin/hledger"
163      }
164    }
165  }
166}
167```
168 
169### Other MCP Clients
170 
171For other MCP-compatible applications, run the server with:
172 
173```bash
174npx @iiatlas/hledger-mcp /path/to/your/master.journal
175```
176 
177The server communicates via stdio and expects the journal file path as the first argument.
178 
179### Write tools
180 
181When the server is not in `--read-only` mode, these tools can modify the primary journal:
182 
183- `hledger_add_transaction` accepts structured postings and appends a new transaction after validating with `hledger check`. Enable `dryRun` to preview the entry without writing.
184- `hledger_remove_entry` deletes a transaction by exact text and location, re-validating with `hledger check` and respecting optional backups.
185- `hledger_replace_entry` swaps an existing entry for new content, keeping spacing tidy and performing a validation pass before committing.
186- `hledger_import` wraps `hledger import`, running the command against a temporary copy of the journal. Provide one or more `dataFiles` (journal, csv, etc.) and an optional `rulesFile`; set `dryRun` to inspect the diff before committing. Successful imports create timestamped `.bak` files unless `--skip-backup` is active.
187- `hledger_rewrite` runs `hledger rewrite` on a temporary copy, letting you specify one or more `addPostings` instructions for matching transactions. Use `dryRun` for a diff-only preview or `diff: true` to include the patch output alongside the applied change.
188- `hledger_close` produces closing/opening assertions, retain-earnings, or clopen transactions via `hledger close`. Preview the generated entries with `dryRun`, then append them atomically (with optional backups) once you’re satisfied.
189 
190All write tools include a `dryRun` parameter to "try it out" before writing.
191 
192### Web tools
193 
194- `hledger_web` launches the hledger web UI/API on a free port unless a specific port/socket is supplied. The response includes an `instanceId` that can be used to track or terminate the server later.
195- `hledger_web_list` returns metadata for each active web instance started by this MCP session (PID, command, base URL, access mode, etc.).
196- `hledger_web_stop` stops a selected instance by `instanceId`, `pid`, or `port`, or stops everything with `all=true`. You can optionally choose the shutdown signal (`SIGTERM` by default) and timeout.
197 
198When the MCP server runs in read-only mode every web instance is forced to `allow: "view"`. Otherwise the server defaults to `allow: "add"` unless `allow: "edit"` is explicitly requested.
199 
200## Example Queries
201 
202Once configured, you can ask Claude natural language questions about your financial data:
203 
204- "What's my current account balance?"
205- "Show me a balance sheet for last quarter"
206- "What were my expenses in the food category last month?"
207- "Generate an income statement for 2024"
208- "Who are my top payees by transaction volume?"
209- "Show me cash flow for the past 6 months"
210 
211## Tool Parameters
212 
213Most tools support common HLedger options including:
214 
215- **Date ranges**: `--begin`, `--end`, `--period`
216- **Output formats**: `txt`, `csv`, `json`, `html`
217- **Account filtering**: Pattern matching and regex support
218- **Calculation modes**: Historical, cumulative, change analysis
219- **Display options**: Flat vs tree view, sorting, percentages
220 
221## Development
222 
223### Building from Source
224 
225```bash
226# Clone the repository
227git clone <repository-url>
228cd hledger-mcp
229 
230# (Optional) If you have nvm, use this version
231nvm use
232 
233# Install dependencies
234npm install
235 
236# Build the server
237npm run build
238 
239# Test
240npm run test
241 
242# Run the debug server
243npm run debug
244```
245 
246### Project Structure
247 
248```
249src/
250├── index.ts              # Main server entry point
251├── base-tool.ts          # Base tool classes and utilities
252├── executor.ts           # Command execution utilities
253├── journal-writer.ts     # Safe journal writing operations
254├── resource-loader.ts    # MCP resource discovery and loading
255├── types.ts              # Shared type definitions
256└── tools/                # Individual tool implementations
257    ├── accounts.ts       # List account names and structures
258    ├── activity.ts       # Account activity analysis
259    ├── add.ts            # Add new transactions
260    ├── balance.ts        # Balance reports
261    └── ...               # ...and many more
262 
263test/
264├── resources/            # Test journal files
265│   ├── master.journal    # Example master journal with includes
266│   ├── 01-jan.journal    # Monthly journal files
267│   ├── 02-feb.journal
268│   └── ...
269├── *.test.ts            # Unit tests for tools and utilities
270└── ...
271```
272 
273## Troubleshooting
274 
275### "hledger CLI is not installed"
276 
277Ensure HLedger is installed and available in your PATH:
278 
279```bash
280hledger --version
281```
282 
283The hledger cli path attempts to be found automatically at common location (see [hledger-path.ts:8](src/hledger-path.ts)). If that's not working, you can set the `HLEDGER_EXECUTABLE_PATH` environment variable to the discrete path.
284 
285```bash
286# Find hledger installation path
287which hledger
288```
289 
290### "hledger web command is failing"
291 
292Not all instances of hledger include the `hledger-web` binary. Additionaly, some installation methods (like `.mcpb`) have a hard time finding it. If you're struggling to launch the web UI I'd recommend first installing or finding the current installation:
293 
294```bash
295# Find hledger-web installation path
296which hledger-web
297```
298 
299Then setting that to the environment variable. For my installation via homebrew, that's:
300 
301```
302HLEDGER_WEB_EXECUTABLE_PATH=/opt/homebrew/bin/hledger-web
303```
304 
305### "Journal file path is required"
306 
307The server requires a journal file path as an argument. Check your config to make sure one is included, and valid.
308 
309### Claude Desktop Connection Issues
310 
3111. Verify the journal file path is correct and accessible
3122. Check that the configuration file syntax is valid JSON
3133. Restart Claude Desktop after configuration changes
314 
315## License
316 
317MIT License (See [LICENSE](LICENSE))
318 
319## Contributing
320 
321See `CONTRIBUTING.md` for setup instructions, coding standards, and tips on testing and debugging changes locally. We welcome issues and pull requests!
322 
323## Related Projects
324 
325- [HLedger](https://hledger.org/) - The underlying accounting software
326- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
327- [Claude Desktop](https://claude.ai/) - AI assistant that supports MCP servers
328