Log inSubmit server
Hledger MCP logo

Hledger MCP

by @iiatlas

Connects AI clients to local hledger journals for reports, analysis, source browsing, and optional validated edits.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Hledger MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "iiatlas-hledger-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@iiatlas/hledger-mcp"
      ],
      "env": {
        "HLEDGER_READ_ONLY": "YOUR_VALUE_HERE",
        "HLEDGER_SKIP_BACKUP": "YOUR_VALUE_HERE",
        "HLEDGER_EXECUTABLE_PATH": "YOUR_VALUE_HERE",
        "HLEDGER_WEB_EXECUTABLE_PATH": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y @iiatlas/hledger-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 1mo ago.

Overview

@iiatlas/hledger-mcp MCP server connects MCP clients to local hledger accounting journals through the hledger command-line interface. It supports account queries, financial reports, transaction analysis, included journal files, and optional journal modifications. Read-only mode disables write access, while write tools provide validation, backups, and dry-run options for supported changes. Use it when an agent needs to inspect or maintain plain-text double-entry accounting data stored on a local system.

Use cases

  • Query local journal balances and account structures
  • Generate income statements and cash flow reports
  • Review transactions across included journal files
  • Preview and append validated journal entries
  • Analyze payees, tags, activity, and transaction notes

Key features

  • Local hledger journal access over MCP stdio
  • Accounting and financial reporting commands
  • Included-journal resource discovery
  • Optional validated journal write operations
  • Dry-run and backup controls
  • hledger web session management

Tools4

What Hledger MCP lets your agent do. Expand a tool for its parameters.

Self-reported~4 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

96/96 checks healthy over the last 72d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 7d ago via OSV.dev · @iiatlas/hledger-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars65Stargazers on the source repository.
npm downloads172Package downloads in the last 30 days.
Last commit8mo agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Tools exposed4Callable tools this server registers over MCP.
Directory activity10 viewsConfig copies, upvotes, and views on AllMCPs.

How Hledger MCP works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Hledger MCP

Install hledger and Node.js 18 or newer, then configure an MCP client to run the published npm package with npx and provide the path to the primary journal. An installable .mcpb file is also available from the project's releases.

Yes. The README provides Claude Desktop configuration using npx, the package name, and a journal-file path.

Add the `--read-only` argument or set `HLEDGER_READ_ONLY` to `true`. This disables write operations.

Yes, when read-only mode is not enabled. It supports adding, removing, replacing, importing, rewriting, and closing entries, with dry-run options for write tools.

Set `HLEDGER_EXECUTABLE_PATH` to the absolute path of the desired hledger binary. A separate `HLEDGER_WEB_EXECUTABLE_PATH` can select the executable used for the web interface.

Related MCP servers

All in Finance & Fintech All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewHledger MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/-iiatlas-hledger-mcp?style=directory)](https://allmcps.com/mcp/-iiatlas-hledger-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/-iiatlas-hledger-mcp"><img src="https://allmcps.com/api/badge/-iiatlas-hledger-mcp?style=directory" alt="Hledger MCP on AllMCPs" /></a>