# @iiatlas/hledger-mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/iiAtlas/hledger-mcp  
**GitHub Stars:** 65  
**npm Downloads (last month):** 104  
**Views:** 7  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/-iiatlas-hledger-mcp

## Description
Double entry plain text accounting, right in your LLM! This MCP enables comprehensive read, and (optional) write access to your local HLedger accounting journals.

## Tools
Capabilities this server exposes over MCP:

- **txt**
- **csv**
- **json**
- **html**

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "hledger-mcp": {
    "command": "npx",
    "args": ["-y","@iiatlas/hledger-mcp"],
    "env": {
      "HLEDGER_READ_ONLY": "",
      "HLEDGER_SKIP_BACKUP": "",
      "HLEDGER_EXECUTABLE_PATH": "",
      "HLEDGER_WEB_EXECUTABLE_PATH": ""
    }
  }
}
```

**Requires environment variables:** `HLEDGER_READ_ONLY`, `HLEDGER_SKIP_BACKUP`, `HLEDGER_EXECUTABLE_PATH`, `HLEDGER_WEB_EXECUTABLE_PATH` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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. The provided material does not specify a software license or support for MCP clients beyond the Claude Desktop configuration and general MCP-client usage.

_Full upstream README: https://allmcps.com/mcp/-iiatlas-hledger-mcp/readme_