mcp-server-ledger

mcp-server-ledger

Model Context Protocol server for interacting with Ledger CLI via AI assistants.

View on GitHub
35
Stars
7
Forks
35
Watchers
3
Issues
mcp-server-ledger provides a standardized Model Context Protocol interface for the Ledger CLI, enabling AI-driven querying and analysis of double-entry accounting data. It exposes key Ledger CLI commands as tools accessible by Large Language Models for financial reporting, budget analysis, and account management. It supports deployment via Docker, Smithery, or 'uv', and requires a valid ledger file and appropriate environment setup.

Key Features

MCP-compliant server for Ledger CLI interaction
Supports balance, register, account, payee, and commodity queries
Budget analysis and statistical summaries
Execution of raw Ledger commands via API
Docker container support
Smithery and uv installation options
Customizable environment via environment variable or config
Formatted and structured output for AI integration
Direct integration with Claude Desktop and other AI assistants

Use Cases

AI-powered financial reporting
Automated budget analysis via AI assistants
Interactive account querying and filtering
Generating transaction registers for review
Extraction of payee and commodity data for analytics
Integration with desktop AI assistants such as Claude Desktop
Raw command experimentation for advanced Ledger users
Automated statistical summaries of financial data
Custom finance bots leveraging the MCP protocol

README

MseeP.ai Security Assessment Badge

mcp-server-ledger: A Ledger CLI MCP Server

smithery badge

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

    • 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

Using Docker (recommended)

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

bash
docker pull minhyeoky/mcp-ledger

Add this to your claude_desktop_config.json:

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:

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

Using uv

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

bash
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:

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:

bash
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.

Star History

Star History Chart

Repository Owner

minhyeoky
minhyeoky

User

Repository Details

Language Python
Default Branch master
Size 32 KB
Contributors 4
MCP Verified Nov 12, 2025

Programming Languages

Python
94.32%
Dockerfile
5.68%

Tags

financial-data docker

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

We respect your privacy. Unsubscribe at any time.

Related MCPs

Discover similar Model Context Protocol servers

  • Bitcoin & Lightning Network MCP Server

    Bitcoin & Lightning Network MCP Server

    Enable AI models to safely interact with Bitcoin and Lightning Network in a standardized way.

    The Bitcoin & Lightning Network MCP Server implements the Model Context Protocol, allowing AI models to interface with Bitcoin and Lightning Network functionalities such as key generation, address validation, transaction decoding, blockchain queries, and lightning payments. It provides standardized endpoints for AI model integration, including support for Claude Desktop and Goose. The solution supports querying blockchain data, parsing transactions and invoices, and managing cryptographic operations in a secure and extensible manner.

    • ⭐ 65
    • MCP
    • AbdelStark/bitcoin-mcp
  • MCP CLI

    MCP CLI

    A powerful CLI for seamless interaction with Model Context Protocol servers and advanced LLMs.

    MCP CLI is a modular command-line interface designed for interacting with Model Context Protocol (MCP) servers and managing conversations with large language models. It integrates with the CHUK Tool Processor and CHUK-LLM to provide real-time chat, interactive command shells, and automation capabilities. The system supports a wide array of AI providers and models, advanced tool usage, context management, and performance metrics. Rich output formatting, concurrent tool execution, and flexible configuration make it suitable for both end-users and developers.

    • ⭐ 1,755
    • MCP
    • chrishayuk/mcp-cli
  • Twelve Data MCP Server

    Twelve Data MCP Server

    Seamless AI-powered access to financial market data via the Twelve Data API.

    Twelve Data MCP Server provides a Model Context Protocol-compliant server for integrating and accessing Twelve Data’s financial market API. It enables users and AI agents to retrieve historical data, real-time quotes, and instrument metadata for stocks, forex, and crypto using natural language or endpoint calls. The system leverages AI-driven routing, including OpenAI GPT-4o, to intelligently map plain English queries to relevant API endpoints for structured or conversational workflows. Integration options are available for platforms like Claude Desktop and VS Code, with flexible local or remote deployment.

    • ⭐ 43
    • MCP
    • twelvedata/mcp
  • mcp-graphql

    mcp-graphql

    Enables LLMs to interact dynamically with GraphQL APIs via Model Context Protocol.

    mcp-graphql provides a Model Context Protocol (MCP) server that allows large language models to discover and interact with GraphQL APIs. The implementation facilitates schema introspection, exposes the GraphQL schema as a resource, and enables secure query and mutation execution based on configuration. It supports configuration through environment variables, automated or manual installation options, and offers flexibility in using local or remote schema files. By default, mutation operations are disabled for security, but can be enabled if required.

    • ⭐ 319
    • MCP
    • blurrah/mcp-graphql
  • mcp-get

    mcp-get

    A command-line tool for discovering, installing, and managing Model Context Protocol servers.

    mcp-get is a CLI tool designed to help users discover, install, and manage Model Context Protocol (MCP) servers. It enables seamless integration of Large Language Models (LLMs) with various external data sources and tools by utilizing a standardized protocol. The tool provides access to a curated registry of MCP servers and supports installation and management across multiple programming languages and environments. Although now archived, mcp-get simplifies environment variable management, package versioning, and server updates to enhance the LLM ecosystem.

    • ⭐ 497
    • MCP
    • michaellatman/mcp-get
  • @dealx/mcp-server

    @dealx/mcp-server

    MCP server enabling LLMs to search and interact with the DealX platform.

    Implements the Model Context Protocol, providing a standardized interface for large language models to interact with the DealX platform. Supports searching for ads through structured prompts and is designed for easy integration with tools like Claude and VS Code extensions. Flexible configuration options are available for environment variables, logging, and deployment. Extensible architecture supports future feature additions beyond ad search.

    • ⭐ 0
    • MCP
    • DealExpress/mcp-server
    • View all Alternatives

    Didn't find tool you were looking for?

    Be as detailed as possible for better results