mcp-server-ledger: 一个账本 CLI 的 MCP 服务器

概述

这是一个用于与 Ledger CLI 交互的 Model Context Protocol 服务器，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

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

7. ledger_stats

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

8. ledger_budget

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

9. ledger_raw_command

   • 运行原始的 Ledger CLI 命令
   • 输入：作为字符串列表的命令参数
   • 返回：命令输出文本

先决条件

• 必须安装 Ledger CLI 并在您的 PATH 中可用
• 一个包含您的财务数据的有效 Ledger 文件

安装

使用 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 检查器进行测试，或与 Claude Desktop 集成进行测试

安全注意事项

此服务器在您的财务数据上运行 Ledger CLI 命令。尽管它包括基本验证以防止命令注入，但您应该：

• 仅与受信任的客户端一起使用
• 注意您暴露的文件路径
• 在执行前审查所有命令

许可证

此 MCP 服务器根据 MIT 许可证发布。请根据许可证条款自由使用、修改和分发。