MCP Server Ledger

🚀 mcp-server-ledger：一个用于与Ledger CLI交互的MCP服务器

一个模型上下文协议（Model Context Protocol，MCP）服务器，用于与总账本命令行界面工具交互。此服务器允许大型语言模型通过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命令
   • 输入：命令参数作为字符串列表
   • 返回：命令输出文本

📦 安装指南

先决条件

• 必须安装并配置好PATH环境变量的Ledger CLI
• 一个有效的总账文件，其中包含您的财务数据

使用uv（推荐）

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

uv sync

💻 使用示例

基础用法

创建新总账文件

uv run mcp-server-ledger@latest ledger --new /path/to/file.ledger

添加日记条目

uv run mcp-server-ledger@latest ledger --add " liabilities:bank" 1000 USD "Initial deposit"

显示账户余额

uv run mcp-server-ledger@latest ledger --balance assets

高级用法

调试服务器

要调试服务器，请运行：

uv server --listen tcp://localhost:1234 mcp-server-ledger@latest --debug

本地开发

要在本地开发，请克隆仓库并安装依赖项：

git clone git@github.com:minhyeoky/mcp-server-ledger.git
cd mcp-server-ledger
npm install

然后启动开发服务器：

uv server --listen tcp://localhost:1234 .

📚 详细文档

配置

该服务器需要指定总账文件的路径。可通过以下方式提供：

• 通过LEDGER_FILE环境变量
• 启动服务器时通过命令行参数提供

使用Claude Desktop

将以下内容添加到您的claude_desktop_config.json中：

"mcpServers": {
  "ledger": {
    "command": "uv server --listen tcp://0.0.0.0:1234 mcp-server-ledger@latest",
    "options": {
      "LEDGER_FILE": "/path/to/your-ledger-file.ledger"
    }
  }
}

⚠️ 安全注意事项

⚠️ 重要提示

• 避免将敏感的财务数据暴露在不安全的网络中。
• 确保总账文件的安全性，防止未经授权的访问。

📄 许可证

该软件受MIT许可证的保护。请参阅LICENSE了解详细信息。