mcp-server-ledger: A Ledger CLI MCP Server

1[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/minhyeoky-mcp-server-ledger-badge.png)](https://mseep.ai/app/minhyeoky-mcp-server-ledger)
2 
3# mcp-server-ledger: A Ledger CLI MCP Server
4 
5[![smithery badge](https://smithery.ai/badge/@minhyeoky/mcp-ledger)](https://smithery.ai/server/@minhyeoky/mcp-ledger)
6 
7## Overview
8 
9A Model Context Protocol server for interacting with [Ledger CLI](https://www.ledger-cli.org/), 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.
10 
11This 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.
12 
13## Features
14 
15The server provides the following tools that map to Ledger CLI commands:
16 
171. `ledger_balance`
18   - Shows account balances with powerful filtering options
19   - Inputs: query pattern, date ranges, display options
20   - Returns: Formatted balance report
21 
222. `ledger_register`
23   - Shows transaction register with detailed history
24   - Inputs: query pattern, date ranges, sorting options
25   - Returns: Formatted register report
26 
273. `ledger_accounts`
28   - Lists all accounts in the ledger file
29   - Input: optional query pattern
30   - Returns: List of matching accounts
31 
324. `ledger_payees`
33   - Lists all payees from transactions
34   - Input: optional query pattern
35   - Returns: List of matching payees
36 
375. `ledger_commodities`
38   - Lists all commodities (currencies) used
39   - Input: optional query pattern
40   - Returns: List of matching commodities
41 
426. `ledger_print`
43   - Prints transactions in ledger format
44   - Inputs: query pattern, date ranges
45   - Returns: Formatted ledger entries
46 
477. `ledger_stats`
48   - Shows statistics about the ledger file
49   - Input: optional query pattern
50   - Returns: Statistical summary of the ledger
51 
528. `ledger_budget`
53   - Shows budget analysis
54   - Inputs: query pattern, date ranges, reporting period
55   - Returns: Budget report
56 
579. `ledger_raw_command`
58   - Runs a raw Ledger CLI command
59   - Input: command arguments as a list of strings
60   - Returns: Command output as text
61 
62## Prerequisites
63 
64- [Ledger CLI](https://www.ledger-cli.org/) must be installed and available in your PATH
65- A valid Ledger file with your financial data
66 
67## Installation
68 
69### Using Docker (recommended)
70 
71You can also use the Docker image from the minhyeoky/mcp-ledger repository:
72 
73```bash
74docker pull minhyeoky/mcp-ledger
75```
76 
77Add this to your `claude_desktop_config.json`:
78 
79```json
80"mcp-ledger": {
81  "command": "docker",
82  "args": [
83    "run",
84    "-v",
85    "/path/to/your/ledger/file.ledger:/main.ledger",
86    "-e",
87    "LEDGER_FILE=/main.ledger",
88    "-i",
89    "--rm",
90    "minhyeoky/mcp-ledger"
91  ]
92}
93```
94 
95Replace `/path/to/your/ledger/file.ledger` with the actual path to your ledger file.
96 
97### Installing via Smithery
98 
99To install Ledger CLI MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@minhyeoky/mcp-ledger):
100 
101```bash
102npx -y @smithery/cli install @minhyeoky/mcp-ledger --client claude
103```
104 
105### Using uv
106 
107The easiest way to install and run this server is with [uv](https://docs.astral.sh/uv/):
108 
109```bash
110uv sync
111```
112## Configuration
113 
114The server requires a path to your Ledger file. This can be provided through:
115 
116- The `LEDGER_FILE` environment variable
117- Command-line arguments when starting the server
118 
119### Using with Claude Desktop
120 
121Add this to your `claude_desktop_config.json`:
122 
123```json
124"mcpServers": {
125  "ledger": {
126    "command": "uv",
127    "args": [
128      "run",
129      "--env-file",
130      "/path/to/your/.env",  // Optional: to set LEDGER_FILE
131      "--with",
132      "mcp[cli]",
133      "mcp",
134      "run",
135      "<repo_path>/main.py"  // Path to the main.py file in this repository
136    ]
137  }
138 
139}
140```
141 
142## Usage Examples
143 
144Once configured, you can ask your AI assistant questions about your financial data:
145 
146- "Show me my expenses for the last month"
147- "What's my current balance in all accounts?"
148- "List all transactions with Amazon"
149- "How much did I spend on groceries in 2023?"
150- "Show me my budget performance for Q1"
151 
152The AI will use the appropriate Ledger CLI commands through the server to get the information.
153 
154## Debugging
155 
156For more detailed local testing:
157 
158```bash
159mcp dev main.py
160```
161 
162## Development
163 
164This server is built using the [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk). For more information about MCP and how to develop MCP servers, see the [official documentation](https://modelcontextprotocol.io).
165 
166To contribute to this project:
167 
1681. Clone the repository
1692. Install development dependencies
1703. Make your changes
1714. Test using the MCP inspector or by integrating with Claude Desktop
172 
173## Security Considerations
174 
175This server runs Ledger CLI commands on your financial data. While it includes basic validation to prevent command injection, you should:
176 
177- Only use with trusted clients
178- Be careful about which file paths you expose
179- Review all commands before execution
180 
181## License
182 
183This MCP server is licensed under the MIT License. Feel free to use, modify, and distribute it according to the license terms.
184