Ledger MCP服务器使用说明

项目简介

Ledger MCP服务器是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在为 LLM 客户端（如 Claude）提供访问和管理 Ledger 账本文件的能力。通过该服务器，Claude 可以调用预设的工具来查询 Ledger 账本中的账户信息，例如列出所有账户、查询账户余额以及获取账户的交易记录。

主要功能点

列出账户 (list-accounts): 允许 Claude 获取指定年份 Ledger 账本中所有账户的列表。
账户余额查询 (account-balance): 允许 Claude 查询指定年份 Ledger 账本中特定账户的当前余额。
账户交易记录查询 (account-register): 允许 Claude 获取指定年份 Ledger 账本中特定账户的详细交易历史记录。

安装步骤

安装 Python 3.13 或更高版本。
安装 'uv' 包管理器。 如果尚未安装，请按照 uv installation instructions 进行安装。

使用 'uv' 安装 'ledger-service' 包:

uv pip install ledger-service

服务器配置

要将 Ledger MCP服务器配置到 MCP 客户端（例如 Claude Desktop），您需要编辑客户端的配置文件。以 Claude Desktop 为例，配置文件路径如下：

MacOS: '~/Library/Application\ Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%/Claude/claude_desktop_config.json'

在配置文件中，找到 '"mcpServers"' 部分，并添加 'ledger-service' 的配置信息。您可以选择以下两种配置方式：

开发配置 (Development Configuration): 适用于开发和调试环境。

  "mcpServers": {
    "ledger-service": {
      "command": "uv",  // 启动命令，使用 uv 运行
      "args": [
        "--directory",  // 参数，指定工作目录
        "/path/to/ledger-service", // 参数，请替换为 ledger-service 包的安装路径。通常如果您直接使用 pip 安装，可以尝试使用 Python 虚拟环境的 site-packages 目录，或者直接使用 'which ledger-service' 命令查找安装路径。
        "run",        // 参数，uv run 子命令
        "ledger-service" // 参数，要运行的模块名 ledger-service
      ]
    }
  }

生产配置 (Production Configuration): 适用于生产环境，假设 'ledger-service' 已添加到系统路径。

  "mcpServers": {
    "ledger-service": {
      "command": "uvx", // 启动命令，使用 uvx 运行 (uvx 通常用于执行安装在虚拟环境或系统路径中的可执行文件)
      "args": [
        "ledger-service" // 参数，要运行的模块名 ledger-service
      ]
    }
  }

注意:

请根据您的实际环境选择合适的配置。
'/path/to/ledger-service' 需要替换为 'ledger-service' 包的实际安装路径。您可以使用 'uv pip show ledger-service' 命令来查看安装路径，或者尝试在 Python 虚拟环境的 'site-packages' 目录下查找。
如果使用生产配置，请确保 'ledger-service' 可执行文件已添加到系统 PATH 环境变量中。

基本使用方法

启动 MCP 客户端 (如 Claude Desktop)。
在 Claude 中，您可以指示 Claude 使用 "ledger-service" 工具来查询 Ledger 账本信息。 例如，您可以向 Claude 提问：
- "列出 2023 年的所有账户" (Claude 可能会调用 'list-accounts' 工具，并传递 'year: "2023"' 参数)
- "查询 'Assets:Checking' 账户在 2024 年的余额是多少" (Claude 可能会调用 'account-balance' 工具，并传递 'year: "2024"', 'account: "Assets:Checking"' 参数)
- "显示 'Expenses:Food' 账户在 2022 年的交易记录" (Claude 可能会调用 'account-register' 工具，并传递 'year: "2022"', 'account: "Expenses:Food"' 参数)

Claude 将会调用 Ledger MCP服务器提供的工具，并将结果返回给您。

前提条件:

您需要拥有 Ledger 账本文件，并将其存储在服务器代码中 'server.py' 文件里 'LEDGER_BASE_PATH' 变量指定的目录下。默认路径为 '/Users/maksymprokopov/personal/ledger'。您可以根据需要修改此路径。
Ledger 账本文件的命名约定为 '[year]/experiment.ledger'，例如 '2023/experiment.ledger'。

关键词