An MCP server that provides AI assistants with direct access to HLedger accounting data and functionality, enabling queries for account balances, generation of financial reports, addition of new entries, and analysis of accounting data through a standardized protocol.

Installation

NPX

npx @iiatlas/hledger-mcp /path/to/your/master.journal

From Source Code

git clone <repository-url>
cd hledger-mcp
npm install
npm run build

Configuration

Claude Desktop (Basic)

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": ["-y", "@iiatlas/hledger-mcp", "/path/to/your/master.journal"]
    }
  }
}

Claude Desktop (Read-Only)

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": [
        "-y",
        "@iiatlas/hledger-mcp",
        "/path/to/your/master.journal",
        "--read-only"
      ]
    }
  }
}

Claude Desktop (Environment Variables)

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": ["-y", "@iiatlas/hledger-mcp", "/path/to/your/master.journal"],
      "env": {
        "HLEDGER_READ_ONLY": "true",
        "HLEDGER_EXECUTABLE_PATH": "/opt/homebrew/bin/hledger"
      }
    }
  }
}

Available Tools

Tool	Description
hledger_accounts	View and query account names and their structure
hledger_balance	Generate balance reports with extensive customization options
hledger_register	View transaction registers and posting details
hledger_print	Output journal entries and transactions
hledger_balance_sheet	Generate balance sheet reports
hledger_balance_sheet_equity	Balance sheet reports with equity details
hledger_income_statement	Generate income statement reports
hledger_cash_flow	Cash flow analysis and reporting
hledger_stats	Statistical analysis of journal data
hledger_activity	Account activity analysis and transaction frequency
hledger_payees	List and analyze payment recipients
hledger_descriptions	Transaction description analysis
hledger_tags	Query and analyze transaction tags
hledger_notes	List unique transaction notes and memo fields
hledger_files	List data files used by hledger

Features

• Support for most hledger CLI commands
• Ability to fetch and traverse !include'd journal files
• Secure --read-only mode
• Comprehensive financial reporting capabilities
• Transaction modification tools with dry-run support
• Automatic backup creation before modifications
• HLedger web interface integration
• MCP resource registration for viewing source registers
• Date ranges, output formats, and account filtering
• Statistical analysis and activity tracking

Environment Variables

Optional

• HLEDGER_READ_ONLY - Set to 'true' to enforce read-only mode
• HLEDGER_SKIP_BACKUP - Set to 'true' to disable automatic .bak backups
• HLEDGER_EXECUTABLE_PATH - Absolute path to a specific hledger binary if not in PATH
• HLEDGER_WEB_EXECUTABLE_PATH - Absolute path to a separate hledger web binary for the web interface

Usage Examples

What is my current account balance?

Show me the balance sheet for the last quarter

What were my food category expenses last month?

Generate an income report for 2024

Who are my top payment recipients by transaction volume?

Notes

Requires HLedger installation with availability in system PATH. Node.js version 18 or higher is required. Available as a .mcpb file from releases or via npm as @iiatlas/hledger-mcp. CLI arguments take priority over environment variables for configuration parameters.