# 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](https://hledger.org/) installed on your system
2. Clone this repository
3. Install dependencies:
   ```bash
   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):

```json
{
  "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:
```bash
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](https://bun.sh/) runtime
- [hledger](https://hledger.org/) 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:
```bash
bun run index.ts
```