mcp-server-ledger: A Ledger CLI MCP Server

mcp-server-ledger：Ledger CLI MCP 服务

概述

这是一个用于与 Ledger CLI 交互的模型上下文协议服务。Ledger CLI 是一款功能强大的复式记账系统，可通过命令行使用。此服务可让大模型通过 Ledger CLI 工具查询和分析您的财务数据。

此 MCP 服务通过标准化接口提供 Ledger CLI 的功能，方便 AI 助手帮助您完成财务报告、预算分析和会计任务。

功能

此服务提供以下与 Ledger CLI 命令对应的工具：

1. ledger_balance

   • 以强大的筛选选项显示账户余额
   • 输入：查询模式、日期范围、显示选项
   • 返回：格式化的余额报告

2. ledger_register

   • 显示包含详细历史记录的交易登记簿
   • 输入：查询模式、日期范围、排序选项
   • 返回：格式化的登记簿报告

3. ledger_accounts

   • 列出账本文件中的所有账户
   • 输入：可选的查询模式
   • 返回：匹配的账户列表

4. ledger_payees

   • 列出所有交易中的收款方
   • 输入：可选的查询模式
   • 返回：匹配的收款方列表

5. ledger_commodities

   • 列出使用的所有商品（货币）
   • 输入：可选的查询模式
   • 返回：匹配的商品列表

6. ledger_print

   • 以 Ledger 格式打印交易
   • 输入：查询模式、日期范围
   • 返回：格式化的账本条目

7. ledger_stats

   • 显示账本文件的统计信息
   • 输入：可选的查询模式
   • 返回：账本统计摘要

8. ledger_budget

   • 显示预算分析
   • 输入：查询模式、日期范围、报告周期
   • 返回：预算报告

9. ledger_raw_command

   • 运行原始 Ledger CLI 命令
   • 输入：以字符串列表形式提供的命令参数
   • 返回：命令输出文本

前提条件

• 必须安装 Ledger CLI，并确保其位于 PATH 中
• 有效的 Ledger 文件，其中包含您的财务数据

安装

使用 Docker（推荐）

您也可以使用 minhyeoky/mcp-ledger 仓库中的 Docker 镜像：

docker pull minhyeoky/mcp-ledger

将以下内容添加到您的 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"
  ]
}

将 /path/to/your/ledger/file.ledger 替换为账本文件的实际路径。

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Ledger CLI MCP Server：

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

使用 uv

使用 uv 安装并运行此服务是最简单的方式：

uv sync

配置

此服务需要您的 Ledger 文件路径。可通过以下方式提供：

• LEDGER_FILE 环境变量
• 启动服务时使用的命令行参数

与 Claude Desktop 搭配使用

将以下内容添加到您的 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
    ]
  }

}

使用示例

配置完成后，您可以向 AI 助手询问有关财务数据的问题：

• “显示我上个月的支出”
• “我所有账户的当前余额是多少？”
• “列出所有与 Amazon 相关的交易”
• “我在 2023 年花了多少钱买杂货？”
• “显示我第一季度的预算执行情况”

AI 将通过此服务使用相应的 Ledger CLI 命令获取信息。

调试

如需进行更详细的本地测试：

mcp dev main.py

开发

此服务使用 Model Context Protocol Python SDK 构建。有关 MCP 以及如何开发 MCP 服务的更多信息，请参阅官方文档。

如需为此项目做出贡献：

1. 克隆代码仓库
2. 安装开发依赖项
3. 进行更改
4. 使用 MCP inspector 测试，或与 Claude Desktop 集成进行测试

安全注意事项

此服务会在你的财务数据上运行 Ledger CLI 命令。虽然它包含基本验证以防止命令注入，但你仍应：

• 仅与可信客户端配合使用
• 谨慎选择要公开的文件路径
• 在执行前检查所有命令

许可证

此 MCP 服务采用 MIT License 授权。你可以根据许可证条款自由使用、修改和分发。