hledger-mcp

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

Built with fastmcp.

Tools

Related MCP server: bookie

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:

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()

get_register

Returns the register report (hledger reg).

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

get_budget

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

get_budget(period="this month")

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
    ]
)

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