ledger

Ledger-service MCP server exposes three tools for working with ledger data via Claude. The tools are: list-accounts, which lists all accounts for a given year; account-balance, which retrieves the current balance for a specified account in a given year; and account-register, which returns the detailed transaction history (register) for an account in a given year. You can invoke these tools through Claude's MCP interface, passing the required parameters (year for all tools; account for the balance and register tools). This server is designed to validate inputs and return structured results you can display or process within Claude.

Prerequisites:

• Python 3.13 or higher
• uv package manager (via uvx for production or uv for development)
• Node.js and npm (optional, for debugging)

Install from PyPI (development workflow using uv):

uv pip install ledger-service

If you plan to debug using the MCP Inspector, ensure Node.js and npm are installed, then you can run:

npx @modelcontextprotocol/inspector \
  uv \
  --directory /path/to/ledger-service \
  run \
  ledger-service

Configure Claude Desktop with the appropriate MCP server entry. Development configuration example:

"mcpServers": {
  "ledger-service": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/ledger-service",
      "run",
      "ledger-service"
    ]
  }
}

Production configuration example (when using uvx):

"mcpServers": {
  "ledger-service": {
    "command": "uvx",
    "args": [
      "ledger-service"
    ]
  }
}

Tips and notes:

• The base path for ledger data can be configured via the LEDGER_BASE_PATH environment variable (if the code supports it; otherwise, set the path in the server configuration).
• Tools expect inputs in a structured way (year is required for all tools; account is required for balance and register). If an invalid year is provided, the server will respond with an error describing the valid range.
• For debugging, use the MCP Inspector to interactively test commands and view responses.
• If you modify server.py or configuration, ensure the path to the ledger data and the tool names remain consistent with the README API.