Skip to main content
Glama
Ledger CLI MCP Server

Ledger CLI MCP Server

by minhyeoky

mcp-server-ledger: A Ledger CLI MCP Server

Overview

A Model Context Protocol server for interacting with Ledger CLI, a powerful, double-entry accounting system accessible from the command line. This server allows Large Language Models to query and analyze your financial data through the Ledger CLI tool.

This MCP server exposes Ledger CLI's functionality through a standardized interface, making it easy for AI assistants to help you with financial reporting, budget analysis, and accounting tasks.

Related MCP server: Lunch Money MCP Server

Features

The server provides the following tools that map to Ledger CLI commands:

  1. ledger_balance

    • Shows account balances with powerful filtering options

    • Inputs: query pattern, date ranges, display options

    • Returns: Formatted balance report

  2. ledger_register

    • Shows transaction register with detailed history

    • Inputs: query pattern, date ranges, sorting options

    • Returns: Formatted register report

  3. ledger_accounts

    • Lists all accounts in the ledger file

    • Input: optional query pattern

    • Returns: List of matching accounts

  4. ledger_payees

    • Lists all payees from transactions

    • Input: optional query pattern

    • Returns: List of matching payees

  5. ledger_commodities

    • Lists all commodities (currencies) used

    • Input: optional query pattern

    • Returns: List of matching commodities

  6. ledger_print

    • Prints transactions in ledger format

    • Inputs: query pattern, date ranges

    • Returns: Formatted ledger entries

  7. ledger_stats

    • Shows statistics about the ledger file

    • Input: optional query pattern

    • Returns: Statistical summary of the ledger

  8. ledger_budget

    • Shows budget analysis

    • Inputs: query pattern, date ranges, reporting period

    • Returns: Budget report

  9. ledger_raw_command

    • Runs a raw Ledger CLI command

    • Input: command arguments as a list of strings

    • Returns: Command output as text

Prerequisites

  • Ledger CLI must be installed and available in your PATH

  • A valid Ledger file with your financial data

Installation

You can also use the Docker image from the minhyeoky/mcp-ledger repository:

docker pull minhyeoky/mcp-ledger

Add this to your claude_desktop_config.json:

"mcp-ledger": {
  "command": "docker",
  "args": [
    "run",
    "-v",
    "/path/to/your/ledger/file.ledger:/main.ledger",
    "-e",
    "LEDGER_FILE=/main.ledger",
    "-i",
    "--rm",
    "minhyeoky/mcp-ledger"
  ]
}

Replace /path/to/your/ledger/file.ledger with the actual path to your ledger file.

Installing via Smithery

To install Ledger CLI MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @minhyeoky/mcp-ledger --client claude

Using uv

The easiest way to install and run this server is with uv:

uv sync

Configuration

The server requires a path to your Ledger file. This can be provided through:

  • The LEDGER_FILE environment variable

  • Command-line arguments when starting the server

Using with Claude Desktop

Add this to your claude_desktop_config.json:

"mcpServers": {
  "ledger": {
    "command": "uv",
    "args": [
      "run",
      "--env-file",
      "/path/to/your/.env",  // Optional: to set LEDGER_FILE
      "--with",
      "mcp[cli]",
      "mcp",
      "run",
      "<repo_path>/main.py"  // Path to the main.py file in this repository
    ]
  }

}

Usage Examples

Once configured, you can ask your AI assistant questions about your financial data:

  • "Show me my expenses for the last month"

  • "What's my current balance in all accounts?"

  • "List all transactions with Amazon"

  • "How much did I spend on groceries in 2023?"

  • "Show me my budget performance for Q1"

The AI will use the appropriate Ledger CLI commands through the server to get the information.

Debugging

For more detailed local testing:

mcp dev main.py

Development

This server is built using the Model Context Protocol Python SDK. For more information about MCP and how to develop MCP servers, see the official documentation.

To contribute to this project:

  1. Clone the repository

  2. Install development dependencies

  3. Make your changes

  4. Test using the MCP inspector or by integrating with Claude Desktop

Security Considerations

This server runs Ledger CLI commands on your financial data. While it includes basic validation to prevent command injection, you should:

  • Only use with trusted clients

  • Be careful about which file paths you expose

  • Review all commands before execution

License

This MCP server is licensed under the MIT License. Feel free to use, modify, and distribute it according to the license terms.

Available Tools

9 tools
ledger_accountsC

List all accounts

Inputs: params (required).

ledger_balanceD

Show account balances

Inputs: params (required).

ledger_budgetD

Show budget report

Inputs: params (required).

ledger_commoditiesC

List all commodities

Inputs: params (required).

ledger_payeesC

List all payees

Inputs: params (required).

ledger_printC

Print transactions in ledger format

Inputs: params (required).

ledger_raw_commandD

Run a raw ledger command

Inputs: params (required).

ledger_registerD

Show transaction register

Inputs: params (required).

ledger_statsC

Show statistics about the ledger file

Inputs: params (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 9 tools

    Disambiguation5/5

    Every tool has a clearly distinct purpose with no ambiguity. Each targets a specific aspect of ledger functionality (e.g., accounts, balances, budget, commodities, payees, printing, raw commands, register, stats), and their descriptions make it easy to differentiate between them.

    Naming Consistency5/5

    All tool names follow a consistent 'ledger_' prefix with a descriptive noun or noun phrase (e.g., ledger_accounts, ledger_balance). This predictable pattern enhances readability and makes the tool set easy to navigate.

    Tool Count5/5

    With 9 tools, the count is well-scoped for a ledger CLI server. Each tool serves a distinct and useful function in managing financial data, and there are no redundant or unnecessary tools, making the set appropriately sized for its domain.

    Completeness4/5

    The tool set provides comprehensive coverage for querying and reporting on ledger data, including accounts, balances, transactions, and statistics. A minor gap is the lack of tools for creating or modifying ledger entries (e.g., add_transaction), but agents can work around this using ledger_raw_command for such operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An experimental server implementing the Model Context Protocol to allow AI assistants to query and analyze financial data stored in Beancount ledger files using the Beancount Query Language.
      53
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows AI assistants to interact with Lunch Money accounts, enabling management of transactions, categories, budgets, and other financial data through natural language commands.
      20 PyPI
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      A Model Context Protocol server that provides AI assistants like Claude with secure, read-only access to MoneyWiz financial data for natural language queries and financial analytics.
      47 PyPI
      15
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that provides programmatic access to Firefly III personal finance management. It enables AI assistants to manage accounts, transactions, budgets, and more through natural language.
      5
      8
      AGPL 3.0