Skip to main content
Glama
hledger-mcp

hledger-mcp

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

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:

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

Available Tools

4 tools
add_transactionAdd TransactionC

Add a new transaction to the journal.

Inputs: date (required), postings (required), description (required). Returns: result

get_balanceGet BalanceA

Show account balances. Optionally filter by account name pattern and/or period (e.g. 'this month', '2026-08', 'Q1').

Inputs: period, account. Returns: result

get_budgetGet BudgetA

Show budget report. Requires budget directives in the journal. Optionally filter by period.

Inputs: period. Returns: result

get_registerGet RegisterA

Show transaction register (history). Optionally filter by account, period, and max number of entries.

Inputs: limit, period, account. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a distinct hledger concern: balances, transaction history, budget reports, and adding transactions. There is no meaningful overlap between them.

    Naming Consistency5/5

    All tools follow the verb_noun pattern with 'get_' for read operations and 'add_' for the write operation. Naming is perfectly predictable and consistent.

    Tool Count5/5

    Four tools is a compact, focused set for a hledger interface covering the most common actions. No tool is redundant, and the scope feels well-suited to an MCP server.

    Completeness3/5

    The core workflows of viewing balances, transactions, budgets, and adding entries are covered. However, there are notable gaps such as no way to list accounts, edit/delete transactions, or retrieve full transaction details, which are common hledger operations.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A Model Context Protocol server that allows AI assistants to query and analyze financial data through Ledger CLI, enabling tasks like financial reporting, budget analysis, and accounting.
      9
      51
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A Model Context Protocol (MCP) server that keeps the books for your personal and business finances using double-entry accounting — driven entirely from an LLM.
      1
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      A read-only MCP server that gives AI agents structured access to a Beancount personal finance ledger.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Double-entry accounting ledger MCP server for autonomous agents that enables creating accounts, posting journal entries, and generating financial reports.
      MIT