mcp server ledger

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.

Features

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

1. ledger_balance
2. Shows account balances with powerful filtering options
3. Inputs: query pattern, date ranges, display options

4. Returns: Formatted balance report

5. ledger_register

6. Shows transaction register with detailed history
7. Inputs: query pattern, date ranges, sorting options

8. Returns: Formatted register report

9. ledger_accounts

10. Lists all accounts in the ledger file
11. Input: optional query pattern

12. Returns: List of matching accounts

13. ledger_payees

14. Lists all payees from transactions
15. Input: optional query pattern

16. Returns: List of matching payees

17. ledger_commodities

18. Lists all commodities (currencies) used
19. Input: optional query pattern

20. Returns: List of matching commodities

21. ledger_print

22. Prints transactions in ledger format
23. Inputs: query pattern, date ranges

24. Returns: Formatted ledger entries

25. ledger_stats

26. Shows statistics about the ledger file
27. Input: optional query pattern

28. Returns: Statistical summary of the ledger

29. ledger_budget

30. Shows budget analysis
31. Inputs: query pattern, date ranges, reporting period

32. Returns: Budget report

33. ledger_raw_command

34. Runs a raw Ledger CLI command
35. Input: command arguments as a list of strings
36. 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

Using uv (recommended)

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.