hledger MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the hledger plain text accounting system.

Features

This MCP server provides the following hledger tools:

Financial Reports

• hledger_balance - Generate balance reports with filtering options
• hledger_incomestatement - Generate income statements
• hledger_balancesheet - Generate balance sheets
• hledger_cashflow - Generate cash flow statements

Transaction Management

• hledger_register - View transaction listings with filtering

Account Management

• hledger_accounts - List all accounts with optional filtering
• hledger_stats - Show journal statistics

Installation

1. Make sure you have hledger installed on your system
2. Clone this repository
3. Install dependencies:

   bun install
   

Configuration for VS Code

When using this MCP server with VS Code, you need to ensure it runs hledger commands in the correct directory. Add the server to your VS Code MCP settings (usually in your VS Code settings):

{
  "mcpServers": {
    "hledger": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/hledger-mcp/index.ts"],
      "env": {
        "LEDGER_FILE": "/path/to/your/finances/main.journal"
      }
    }
  }
}

File Resolution Priority

The server resolves which hledger file to use in this order:

1. Explicit file parameter - if provided in the tool call
2. LEDGER_FILE environment variable - if set
3. hledger's default file discovery - follows hledger's standard rules

Working Directory Handling

The MCP server supports several ways to specify which hledger files to use:

Option 1: Use LEDGER_FILE Environment Variable (Recommended)

Set the LEDGER_FILE environment variable in your MCP server configuration. The server will automatically use the journal file specified in $LEDGER_FILE.

Option 2: Use the workingDirectory Parameter

All tools accept an optional workingDirectory parameter that specifies where hledger commands should be executed.

Option 3: Use Absolute File Paths

You can specify the exact path to your journal file using the file parameter.

Option 4: Use Relative Paths with Working Directory

If your journal files are in a specific directory structure, you can combine the workingDirectory parameter with a relative file path.

Usage

As an MCP Server

Run the server in stdio mode:

bun run index.ts

Tool Parameters

Common Parameters

• file (optional): Path to specific hledger journal file (overrides $LEDGER_FILE env var)
• workingDirectory (optional): Directory to run hledger commands from (defaults to current directory)
• period (optional): Time period filter using natural language (e.g., "this month", "2024", "last quarter")
• beginDate (optional): Precise begin date for filtering (YYYY-MM-DD, YYYY-MM, or YYYY)
• endDate (optional): Precise end date for filtering (YYYY-MM-DD, YYYY-MM, or YYYY)
• depth (optional): Account depth limit for reports

Note: Use beginDate/endDate for precise date ranges and monthly averages. If both period and beginDate/endDate are provided, the specific dates take precedence.

Environment Variables

• LEDGER_FILE: Default journal file path (used when no explicit file is specified)

hledger_balance

• accounts (optional): Account pattern to filter
• period (optional): Natural language time period (e.g., "this month", "2024")
• beginDate (optional): Begin date for filtering (YYYY-MM-DD or YYYY-MM or YYYY)
• endDate (optional): End date for filtering (YYYY-MM-DD or YYYY-MM or YYYY)
• monthly (optional): Show monthly breakdown
• average (optional): Show averages over the reporting period
• flat (optional): Show flat account list instead of tree

hledger_register

• query (optional): Query to filter transactions
• period (optional): Natural language time period (e.g., "this month", "2024")
• beginDate (optional): Begin date for filtering (YYYY-MM-DD or YYYY-MM or YYYY)
• endDate (optional): End date for filtering (YYYY-MM-DD or YYYY-MM or YYYY)
• monthly (optional): Show monthly breakdown
• width (optional): Output width (default: 80)

hledger_accounts

• pattern (optional): Pattern to filter accounts
• tree (optional): Show accounts in tree format

Requirements

• Bun runtime
• hledger CLI tool
• Node.js compatible environment

Development

The server is built using:

• Bun for JavaScript runtime and process execution
• Model Context Protocol SDK for MCP server functionality
• Zod for input validation

To run in development mode:

bun run index.ts