JinDaGe - mcp-server-ledger MCP Details

article

README

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

一个模型上下文协议（Model Context Protocol，MCP）服务器，用于与总账本命令行界面工具交互。此服务器允许大型语言模型通过Ledger CLI工具查询和分析您的财务数据，可帮助完成财务报告、预算分析和会计任务。

🚀 快速开始

此MCP服务器通过标准接口公开了Ledger CLI的功能，使AI助手能够轻松帮助您完成财务报告、预算分析和会计任务。通过以下徽章和链接，您可以快速了解该项目：

✨ 主要特性

该服务器提供了以下工具，这些工具映射到Ledger CLI命令：

ledger_balance
- 显示带有强大过滤选项的账户余额
- 输入：查询模式、日期范围、显示选项
- 返回：格式化的余额报告
ledger_register
- 显示详细的交易记录
- 输入：查询模式、日期范围、排序选项
- 返回：格式化的注册报告
ledger_accounts
- 列出总账文件中的所有账户
- 输入：可选查询模式
- 返回：匹配账户列表
ledger_payees
- 列出交易中的所有付款人
- 输入：可选查询模式
- 返回：匹配的付款人列表
ledger_commodities
- 列出使用的商品（货币）
- 输入：可选查询模式
- 返回：匹配的商品列表
ledger_print
- 以总账格式打印交易
- 输入：查询模式、日期范围
- 返回：格式化的总账条目
ledger_stats
- 显示关于总账文件的统计信息
- 输入：可选查询模式
- 返回：总账摘要统计信息
ledger_budget
- 显示预算分析
- 输入：查询模式、日期范围、报告周期
- 返回：预算报告
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了解详细信息。

mcp-server-ledger