HL
AI & MLFinance

HLedger MCP Server: LLM Access to Double-Entry Journals

Enable LLM access to your local HLedger double-entry journals with an MCP server for comprehensive read and optional write operations on plain-text accounting.

View on GitHub
Quick Install
npx -y @iiAtlas/hledger-mcp

Overview

This MCP (Model Context Protocol) server bridges local HLedger double-entry plain-text journals and LLMs, making your accounting data available as structured tools that language models can call. It parses HLedger journal files, exposes read operations (account lists, balances, registers, transaction search, exports) and optional write operations (proposed transactions, apply/commit) through an MCP-compatible HTTP interface so LLM agents can inspect, analyze, and suggest edits to your books.

That combination is useful when you want conversational access to your financial history (e.g., ask an assistant for “last month’s rent payments” or “what’s the current cash balance?”) or to leverage LLMs to help draft bookkeeping entries. The server keeps journals as plain text, preserves HLedger workflows, and can be run in read-only mode for security or configured to require manual approval for any write operations.

Features

  • Exposes HLedger journals to LLMs via the Model Context Protocol (MCP)
  • Read operations: list accounts, balances, transaction registers, searches, and exports
  • Write operations (optional): propose, validate, and apply journal entries
  • Supports multiple journal files and includes HLedger-style includes
  • Configurable server (port, journal paths, read-only or write-enabled)
  • Simple HTTP JSON API compatible with MCP tool invocation patterns
  • Authentication and safe defaults to avoid accidental writes
  • Works with local tooling, containers, or systemd services

Installation / Configuration

Prerequisites: you need HLedger installed and your journal files available locally.

Clone and run (generic example):

git clone https://github.com/iiAtlas/hledger-mcp.git
cd hledger-mcp

# Option A: run with provided Python/Go binary (if included)
./hledger-mcp \
  --journals "/path/to/journal.journal:/path/to/other.journal" \
  --port 8080 \
  --mode read-only

# Option B: Docker
docker build -t hledger-mcp .
docker run -v /path/to/journals:/journals -p 8080:8080 \
  -e HLEDGER_JOURNALS="/journals/main.journal" \
  -e MCP_PORT=8080 \
  iiatlas/hledger-mcp:latest

Environment variables and CLI flags (typical):

# Example environment variables
HLEDGER_JOURNALS=/home/user/finance/main.journal:/home/user/finance/expenses.journal
MCP_PORT=8080
MCP_MODE=read-only        # or read-write
MCP_API_KEY=replace-with-secret

Example systemd service unit (install as /etc/systemd/system/hledger-mcp.service):

[Unit]
Description=hledger-mcp server
After=network.target

[Service]
Environment="HLEDGER_JOURNALS=/home/ledger/journal.journal"
Environment="MCP_PORT=8080"
Environment="MCP_MODE=read-only"
ExecStart=/usr/local/bin/hledger-mcp
Restart=on-failure
User=ledger
Group=ledger

[Install]
WantedBy=multi-user.target

Security tips:

  • Run in read-only mode unless you need write functionality.
  • Use an API key and network restrictions for production.
  • Keep backups of your journal files before enabling automatic writes.

Available Tools / Resources

The server registers a predictable set of MCP tools representing common bookkeeping operations. Tool names and behavior may vary slightly by release; expect at least these:

Tool namePurpose
hledger.list_accountsReturn account hierarchy and metadata
hledger.get_balanceGet balance for an account (with date range)
hledger.registerReturn register (transactions) for an account or query
hledger.search_transactionsFull-text or field-filtered transaction search
hledger.exportProduce HLedger-formatted export (CSV/JSON)
hledger.suggest_transactionAsk the server to draft a new journal entry based on natural language input (validation only)
hledger.apply_transactionApply a proposed transaction to journal files (requires write-enabled mode and auth)

API pattern (example):

  • GET /mcp/tools — list registered tools and schemas
  • POST /mcp/tool/{tool_name} — invoke a tool with JSON payload
  • POST /mcp/transactions/propose — create a draft transaction (response: draft text + validation)
  • POST /mcp/transactions/apply — apply draft to file (requires write mode & API key)

Example curling a tool:

curl -X POST http://localhost:8080/mcp/tool/hledger.get_balance \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account": "Assets:Bank:Checking", "as_of": "2026-03-31"}'

Use Cases

  • Natural-language bookkeeping queries

    • “Show me all rent payments in 2025 and total by landlord.”
    • LLMs call hledger.search_transactions, summarize results, and can export CSV.

  • Interactive reconciliation

    • Ask the assistant: “Why is my cash balance different from the bank statement?”
    • The agent pulls a register, identifies suspicious transactions, and suggests possible corrections.

  • Drafting and validating transactions

    • Tell the LLM: “Record the $500 invoice payment to Vendor X on 2026-04-01.”
    • The assistant uses hledger.suggest_transaction to produce a candidate journal entry; after review, hledger.apply_transaction writes it.

  • Financial summaries and reporting

    • Generate monthly P&L, balance-sheets, or cash flow snapshots by invoking hledger.export or hledger.get_balance across accounts.

  • Automation and integrations

    • Combine with automation workflows to propose entries from bank statements, then require human sign-off before applying.

Notes and Best Practices

  • Keep your journal files in version control or regular backups; write operations change plain text files.
  • Prefer read-only mode when first integrating or for LLM sandboxing.
  • Use explicit user confirmation for any write operation; do not enable auto-commit without a review step.
  • Validate tool responses and restrict access with network-level policies and API keys.

For full

Tags:ai-mlfinance