MCP Server Ledger

🚀 mcp-server-ledger: An MCP Server for Interacting with Ledger CLI

An MCP (Model Context Protocol) server that enables interaction with the Ledger Command-Line Interface, a powerful double-entry accounting system accessible via the command line. This server allows large language models to query and analyze your financial data through the Ledger CLI.

🚀 Quick Start

This is a Model Context Protocol (MCP) server designed to interact with the Ledger Command-Line Interface. The Ledger CLI is a powerful double-entry accounting system accessible via the command line. This server enables large language models to query and analyze your financial data through the Ledger CLI tool. It exposes the functionality of the Ledger CLI through a standard interface, allowing AI assistants to easily assist with financial reporting, budget analysis, and accounting tasks.

✨ Features

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

1. ledger_balance

   • Displays account balances with powerful filtering options.
   • Input: Query mode, date range, display options.
   • Returns: Formatted balance report.

2. ledger_register

   • Displays detailed transaction records.
   • Input: Query mode, date range, sorting options.
   • Returns: Formatted register report.

3. ledger_accounts

   • Lists all accounts in the ledger file.
   • Input: Optional query mode.
   • Returns: List of matching accounts.

4. ledger_payees

   • Lists all payees in transactions.
   • Input: Optional query mode.
   • Returns: List of matching payees.

5. ledger_commodities

   • Lists the commodities (currencies) in use.
   • Input: Optional query mode.
   • Returns: List of matching commodities.

6. ledger_print

   • Prints transactions in ledger format.
   • Input: Query mode, date range.
   • Returns: Formatted ledger entries.

7. ledger_stats

   • Displays statistics about the ledger file.
   • Input: Optional query mode.
   • Returns: Summary statistics of the ledger.

8. ledger_budget

   • Displays budget analysis.
   • Input: Query mode, date range, reporting period.
   • Returns: Budget report.

9. ledger_raw_command

   • Executes raw Ledger CLI commands.
   • Input: Command parameters as a list of strings.
   • Returns: Command output text.

📦 Installation

Using uv (Recommended)

Using uv is the simplest way to install and run the server:

uv sync

💻 Usage Examples

Create a New Ledger File

uv run mcp-server-ledger@latest ledger --new /path/to/file.ledger

Add a Journal Entry

uv run mcp-server-ledger@latest ledger --add " liabilities:bank" 1000 USD "Initial deposit"

Display Account Balances

uv run mcp-server-ledger@latest ledger --balance assets

📚 Documentation

Prerequisites

• Ledger CLI must be installed and the PATH environment variable properly configured.
• A valid ledger file containing your financial data.

Configuration

The server requires the path to the ledger file to be specified. This can be provided in the following ways:

• Through the LEDGER_FILE environment variable.
• As a command-line argument when starting the server.

Using Claude Desktop

Add the following to your claude_desktop_config.json:

"mcpServers": {
  "ledger": {
    "command": "uv server --listen tcp://0.0.0.0:1234 mcp-server-ledger@latest",
    "options": {
      "LEDGER_FILE": "/path/to/your-ledger-file.ledger"
    }
  }
}

Debugging

To debug the server, run:

uv server --listen tcp://localhost:1234 mcp-server-ledger@latest --debug

Development

To develop locally, clone the repository and install the dependencies:

git clone git@github.com:minhyeoky/mcp-server-ledger.git
cd mcp-server-ledger
npm install

Then start the development server:

uv server --listen tcp://localhost:1234 .

Security Considerations

• Avoid exposing sensitive financial data on insecure networks.
• Ensure the security of the ledger file to prevent unauthorized access.

📄 License

This software is protected by the MIT license. See LICENSE for details.