Ledger CLI MCP Server
The Ledger CLI MCP Server allows AI assistants to interact with financial data stored in Ledger CLI files, enabling querying, reporting, and analysis. You can:
View account balances with filtering by date range, depth, and grouping options (daily, weekly, monthly, yearly)
Generate transaction registers with sorting, filtering, and grouping by payee or timeframe
List accounts, payees, or commodities (currencies) with optional pattern filtering
Print transactions in ledger format with date range filtering
View statistics about the ledger file
Generate budget reports with filtering and timeframe grouping
Execute raw Ledger CLI commands for advanced use cases
Used to set the LEDGER_FILE environment variable for configuring the path to the user's ledger file
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Ledger CLI MCP Server show me my expenses for groceries last month"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
ledger_balanceShows account balances with powerful filtering options
Inputs: query pattern, date ranges, display options
Returns: Formatted balance report
ledger_registerShows transaction register with detailed history
Inputs: query pattern, date ranges, sorting options
Returns: Formatted register report
ledger_accountsLists all accounts in the ledger file
Input: optional query pattern
Returns: List of matching accounts
ledger_payeesLists all payees from transactions
Input: optional query pattern
Returns: List of matching payees
ledger_commoditiesLists all commodities (currencies) used
Input: optional query pattern
Returns: List of matching commodities
ledger_printPrints transactions in ledger format
Inputs: query pattern, date ranges
Returns: Formatted ledger entries
ledger_statsShows statistics about the ledger file
Input: optional query pattern
Returns: Statistical summary of the ledger
ledger_budgetShows budget analysis
Inputs: query pattern, date ranges, reporting period
Returns: Budget report
ledger_raw_commandRuns 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
Using Docker (recommended)
You can also use the Docker image from the minhyeoky/mcp-ledger repository:
docker pull minhyeoky/mcp-ledgerAdd 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 claudeUsing uv
The easiest way to install and run this server is with uv:
uv syncConfiguration
The server requires a path to your Ledger file. This can be provided through:
The
LEDGER_FILEenvironment variableCommand-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.pyDevelopment
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:
Clone the repository
Install development dependencies
Make your changes
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 toolsledger_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Log, query, and edit expenses, budgets, and accounts in Ledgy from any MCP-compatible AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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.53MIT
- AlicenseNot gradedqualityDmaintenanceA 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 PyPIMIT
- AlicenseNot gradedqualityAmaintenanceA 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 PyPI15MIT
- AlicenseBqualityDmaintenanceA 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.58AGPL 3.0