🚀 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了解详细信息。