hledger-mcp

MCP server for hledger — exposes double-entry accounting tools to AI agents via the Model Context Protocol.

Built with fastmcp.

Tools

Tool	Description
get_balance	Account balances, optionally filtered by account and period
get_register	Transaction history, optionally filtered by account, period, and limit
get_budget	Budget report (requires budget directives in the journal)
add_transaction	Append a new transaction to the journal

Requirements

• Python 3.11+
• hledger installed and on PATH
• uv (for uvx invocation)

Usage

Run directly with uvx

uvx --from /path/to/hledger-mcp hledger-mcp

Add to Claude Code

{
  "mcpServers": {
    "hledger": {
      "command": "uvx",
      "args": ["--from", "/path/to/hledger-mcp", "hledger-mcp"]
    }
  }
}

Journal path

By default, the server reads and writes to ~/hledger.journal. Override with the HLEDGER_JOURNAL environment variable:

HLEDGER_JOURNAL=/path/to/my.journal uvx --from /path/to/hledger-mcp hledger-mcp

Or in mcp.json:

{
  "mcpServers": {
    "hledger": {
      "command": "uvx",
      "args": ["--from", "/path/to/hledger-mcp", "hledger-mcp"],
      "env": {
        "HLEDGER_JOURNAL": "/home/user/finance/ledger.journal"
      }
    }
  }
}

Using with orbit

orbit is an AI session launcher that manages context — MCPs, instructions, and permissions — across a layered scope hierarchy: workspace → tenant → project → repository. hledger ships as a first-class orbit plugin.

Setup (3 commands)

# Register the plugin with orbit
curl -fsSL https://raw.githubusercontent.com/eloircorona/hledger-mcp/main/hledger.toml \
  -o ~/.orbit/plugins/hledger.toml

# Install hledger if not already present
orbit plugins install hledger

# Configure the journal path for this instance
orbit plugins auth hledger

# Enable the MCP for the current scope (tenant, project, or global)
orbit plugins enable hledger

orbit plugins auth prompts for the instance name and journal path, then wires everything up. No config files to edit manually.

If you already cloned the repo, the one-liner becomes:

cp hledger.toml ~/.orbit/plugins/

Launch

orbit launch <scope>

orbit starts the session with hledger connected alongside any other MCPs in scope. Switch to a different tenant and hledger disappears automatically.

Multiple journals

Need separate instances for personal and business finances? Run orbit plugins auth hledger again with a different instance name — orbit tracks them independently:

orbit plugins auth hledger   # instance: personal → ~/finance/personal.journal
orbit plugins auth hledger   # instance: business → ~/finance/business.journal

Why this matters

A typical personal finance setup in orbit pairs hledger-mcp with:

MCP	Purpose
hledger	Typed access to the journal — query balances, add transactions
filesystem	Browse receipts, bank exports, tax documents
sqlite	Structured queries over imported CSV data

Because orbit merges MCPs layer by layer, you can scope hledger to a specific tenant so it only loads when you're working on finances — never leaking into other sessions.

orbit handles context scoping, MCP lifecycle, engine selection (Claude, Gemini, local), and session instructions — so the AI always has the right tools for the current domain, with zero manual configuration per session.

Tool reference

get_balance

Returns the balance report (hledger bal).

get_balance(account="gastos", period="this month")
get_balance(account="activos:banco")
get_balance()

Param	Type	Description
account	str (optional)	Account name pattern to filter
period	str (optional)	Period expression: "this month", "2026-08", "Q1", "last year", etc.

get_register

Returns the register report (hledger reg).

get_register(account="gastos:alimentacion", period="this month")
get_register(limit=20)

Param	Type	Description
account	str (optional)	Account name pattern to filter
period	str (optional)	Period expression
limit	int (optional)	Max number of entries to return

get_budget

Returns the budget report (hledger budget). Requires ~ monthly or similar budget directives in your journal.

get_budget(period="this month")

Param	Type	Description
period	str (optional)	Period expression

add_transaction

Appends a transaction to the journal file.

add_transaction(
    date="2026-08-08",
    description="Supermercado Walmart",
    postings=[
        {"account": "gastos:alimentacion", "amount": "850 MXN"},
        {"account": "activos:banco:bbva"},   # no amount — hledger auto-balances
    ]
)

Param	Type	Description
date	str	ISO date: "2026-08-08"
description	str	Payee or description
postings	list[dict]	List of {"account": str, "amount": str}. Last entry may omit amount.

The resulting journal entry:

2026-08-08 Supermercado Walmart
    gastos:alimentacion                       850 MXN
    activos:banco:bbva

Account conventions (hledger standard)

activos:      assets  (bank, cash, investments)
pasivos:      liabilities  (credit cards, loans)
ingresos:     income  (salary, freelance)
gastos:       expenses  (food, transport, rent)
patrimonio:   equity  (opening balances)

Development

git clone git@github.com:eloircorona/hledger-mcp.git
cd hledger-mcp
uv sync
uv run hledger-mcp

License

MIT