hledger MCP

MCP server for hledger — plain-text accounting. It gives AI agents read/write access to your journals. Works with any MCP client (OpenCode, Claude Desktop, Cursor, …).

Quick start

# Run directly (no install needed)
uvx hledger-mcp --journal /path/to/main.journal

# Or install globally
uv tool install hledger-mcp
hledger-mcp --journal /path/to/main.journal

The journal path can also come from the LEDGER_FILE environment variable.

Related MCP server: ledgerkit-mcp

MCP client setup

OpenCode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "hledger": {
      "type": "local",
      "command": ["uvx", "hledger-mcp", "--journal", "/path/to/main.journal"],
      "enabled": true
    }
  }
}

Claude Desktop (claude_desktop_config.json):

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

Example

"How much did I spend on groceries last month?"

The agent calls hledger_balance(account="expenses:groceries", monthly=True).

"Record a 15 euro grocery purchase at Esselunga paid with my bank card."

The agent calls hledger_add_transaction() with:

2026-07-28 Esselunga
    expenses:groceries    15.00 EUR
    assets:bank

Say "check if it is valid first" and the agent will validate with dry_run=True before touching your journal.

Tools

Safety

Every write is backed up, validated with hledger check, and rolled back on failure. dry_run=True validates against a temp file and never touches your journal.

Requirements

• Python >= 3.12, hledger in PATH, uv (or pip)