hledger-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hledger-mcp show my balance for the current month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Account balances, optionally filtered by account and period |
| Transaction history, optionally filtered by account, period, and limit |
| Budget report (requires |
| Append a new transaction to the journal |
Related MCP server: bookie
Requirements
Usage
Run directly with uvx
uvx --from /path/to/hledger-mcp hledger-mcpAdd 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-mcpOr 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 hledgerorbit 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.journalWhy this matters
A typical personal finance setup in orbit pairs hledger-mcp with:
MCP | Purpose |
| Typed access to the journal — query balances, add transactions |
| Browse receipts, bank exports, tax documents |
| 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 name pattern to filter |
|
| Period expression: |
get_register
Returns the register report (hledger reg).
get_register(account="gastos:alimentacion", period="this month")
get_register(limit=20)Param | Type | Description |
|
| Account name pattern to filter |
|
| Period expression |
|
| 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 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 |
|
| ISO date: |
|
| Payee or description |
|
| List of |
The resulting journal entry:
2026-08-08 Supermercado Walmart
gastos:alimentacion 850 MXN
activos:banco:bbvaAccount 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-mcpLicense
MIT
Available Tools
4 toolsadd_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
Scored across 4 tools
Each tool targets a distinct hledger concern: balances, transaction history, budget reports, and adding transactions. There is no meaningful overlap between them.
All tools follow the verb_noun pattern with 'get_' for read operations and 'add_' for the write operation. Naming is perfectly predictable and consistent.
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.
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
Log, query, and edit expenses, budgets, and accounts in Ledgy from any MCP-compatible AI assistant.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Related MCP Servers
- AlicenseCqualityDmaintenanceA 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.951MIT
- AlicenseNot gradedqualityBmaintenanceA Model Context Protocol (MCP) server that keeps the books for your personal and business finances using double-entry accounting — driven entirely from an LLM.1MIT
- FlicenseNot gradedqualityCmaintenanceA read-only MCP server that gives AI agents structured access to a Beancount personal finance ledger.1-
- AlicenseNot gradedqualityCmaintenanceDouble-entry accounting ledger MCP server for autonomous agents that enables creating accounts, posting journal entries, and generating financial reports.MIT