HLedgerBLOCK
A local MCP server for interacting with the HLedger cli
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
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 tran
a18a6f3ff896OBSERVED · 2026-10-07Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add hledger-mcp --env MCP_AUTH_PORT=${MCP_AUTH_PORT} -- npx -y @iiatlas/[email protected]{
"mcpServers": {
"hledger-mcp": {
"command": "npx",
"args": [
"-y",
"@iiatlas/[email protected]"
],
"env": {
"MCP_AUTH_PORT": "${MCP_AUTH_PORT}"
}
}
}
}Exposed tools (36)
30 read · 5 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
collect-user-info | read | A tool that collects user information through elicitation |
full | read | full options |
get_weather | read | |
greet | read | A simple greeting tool |
hello | read | world |
hledger_accounts | read | List account names from the journal, with optional filtering and formatting |
hledger_activity | read | Show posting activity counts as a bar chart |
hledger_add_transaction | write | Add a new transaction to the journal file using structured input |
hledger_balance | read | Show account balances, balance changes, or other balance-related reports with extensive customization options |
hledger_balancesheet | read | Summarize assets and liabilities with balance sheet layout |
hledger_balancesheetequity | read | Balance sheet including equity accounts |
hledger_cashflow | read | Cash flow statement showing liquidity changes |
hledger_close | read | Generate and optionally append closing/opening transactions to the journal |
hledger_descriptions | read | List transaction descriptions from the journal |
hledger_files | read | List data files in use by hledger |
hledger_find_entry | read | Find complete journal entries matching a query |
hledger_import | write | Import transactions from external data files using hledger |
hledger_incomestatement | read | Income statement summarizing revenues and expenses |
hledger_notes | read | List unique transaction notes, optionally filtered by query |
hledger_payees | read | List payee names from the journal, optionally filtered and sorted |
hledger_print | read | Print full transactions from the journal with optional filtering and formatting |
hledger_register | read | Show postings with running totals, filtered by query or account |
hledger_remove_entry | destructive | Remove a complete journal entry by exact match |
hledger_replace_entry | read | Replace a complete journal entry with new content |
hledger_rewrite | read | Rewrite matching transactions by adding postings using hledger |
hledger_stats | read | Show journal statistics and health metrics |
hledger_tags | read | List tag names used in transactions |
hledger_web | write | Start the hledger web interface server without blocking |
hledger_web_list | read | List active hledger web instances started by this MCP server |
hledger_web_stop | write | Stop one or more hledger web server instances |
list-files | read | |
multi-greet | read | A tool that sends different greetings with delays between them |
number | read | number |
query | read | |
start-notification-stream | write | Starts sending periodic notifications |
test | read | test |
Trust audit
BLOCKgrade F · trust 27/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | WARN |
| L1 | Static analysis of the code | FAIL |
| L2 | Instruction surface (what it tells the agent) | FAIL |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (4 observation(s))
- Network
- declared (4 observation(s))
- Shell
- declared (9 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (25)
exec(sql: string): void;
exec(input?: string | URLPatternInit, baseURL?: string): URLPatternResult | null;
var makeValidate = new Function(
var makeValidate = new Function(
request ~ requests
request ~ requests
# MIT License
node_modules/.bin/node-which
node_modules/.bin/tsc
node_modules/.bin/tsserver
* console.log(myURL.password);
"chars": "€پ‚ƒ„...†‡ˆ‰ٹ‹Œچژڈگ‘’“”•–—کTMڑ›œں ،¢£¤¥¦§ ̈©ھ«¬® ̄°±23 ́μ¶· ̧1؛»1⁄41⁄23⁄4؟ہءآأؤإئابةتثجحخدذرزسشصض×طظعغـفقكàلâمنهوçèéêëىيîïًٌٍَôُِ÷ّùْûüے"
"chars": "«»...“”�•‘’� กขฃคฅฆงจฉชซฌญฎฏฐฑฒณดตถทธนบปผฝพฟภมยรฤลฦวศษสหฬอฮฯะัาําิีึืฺุู–—฿เแโใไๅๆ็่้๊๋์ํTM๏๐๑๒๓๔๕๖๗๘๙®©����"
"chars": "€پ‚ƒ„...†‡ˆ‰ٹ‹Œچژڈگ‘’“”•–—کTMڑ›œں ،¢£¤¥¦§ ̈©ھ«¬® ̄°±23 ́μ¶· ̧1؛»1⁄41⁄23⁄4؟ہءآأؤإئابةتثجحخدذرزسشصض×طظعغـفقكàلâمنهوçèéêëىيîïًٌٍَôُِ÷ّùْûüے"
"chars": "«»...“”�•‘’� กขฃคฅฆงจฉชซฌญฎฏฐฑฒณดตถทธนบปผฝพฟภมยรฤลฦวศษสหฬอฮฯะัาําิีึืฺุู–—฿เแโใไๅๆ็่้๊๋์ํTM๏๐๑๒๓๔๕๖๗๘๙®©����"
<div style="background-color: white; padding: 4px; padding-bottom: 8px;" alt="stainless">
hledger_remove_entry
.mcpbignore
.prettierignore
.tonic_example.js
.eslintrc.yml
.nycrc
exec(command, (error) => {.createHash('sha1')console.log(`Using resumption token: ${notificationsToolLastEventId || 'none'}`);Gates applied: no_behavioural_pass.
a18a6f3ff896full audit observations/trust-audit/mcp-server/iiatlas__hledger.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-07 | a18a6f3ff896 | BLOCK | F | 27 | first audit |
Questions
What is the HLedger MCP server?
A local MCP server for interacting with the HLedger cli
What tools does HLedger expose?
36 in total: 30 read-only, 5 that write, and 1 that can delete or overwrite (hledger_remove_entry). Every one is listed on this page with its risk.
Is HLedger safe to connect to an agent?
No — not without reading the findings first. The audit graded it F (27/100) and found 7 critical or high issues in the source. Each one is listed on this page with the file and line it is on. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does HLedger need?
It reads MCP_AUTH_PORT from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does HLedger run?
It speaks sse, stdio and streamable-http, so it runs as a local process your client starts. It is published on npm as @iiatlas/hledger-mcp at 1.0.5.
How current is this page?
The grade is for one exact copy of the source (a18a6f3ff896), read on 2026-10-07. The repository is watched and re-audited when it changes.