项目介绍
mcp-server-ledger: 一个与Ledger CLI交互的账本MCP服务器
概述
这是一个用于与Ledger CLI交互的模型上下文协议（MCP）服务器。Ledger CLI是一个强大的双入账会计系统，可以通过命令行访问。此服务器允许大型语言模型通过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
- 包含您的财务数据的有效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自动安装Ledger CLI MCP服务器给Claude Desktop：
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", // 可选：设置LEDGER_FILE
"--with",
"mcp[cli]",
"mcp",
"run",
"<repo_path>/main.py" // 本仓库中main.py文件的路径
]
}
}
使用示例
配置完成后，您可以向您的AI助手询问有关您的财务数据的问题：
- "给我看看我上个月的支出"
- "我现在所有账户的余额是多少？"
- "列出所有与亚马逊的交易"
- "我在2023年花了多少钱在杂货上？"
- "给我看看第一季度的预算表现"
AI将通过服务器使用适当的Ledger CLI命令来获取信息。
调试
为了进行更详细的本地测试：
mcp dev main.py
开发
此服务器使用Model Context Protocol Python SDK构建。关于MCP及其如何开发MCP服务器的更多信息，请参阅官方文档。
要为此项目做出贡献：
- 克隆仓库
- 安装开发依赖项
- 进行更改
- 使用MCP检查器或集成到Claude Desktop进行测试
安全注意事项
此服务器会在您的财务数据上运行Ledger CLI命令。虽然它包含基本验证以防止命令注入，但您应该：
- 仅与受信任的客户端使用
- 小心暴露哪些文件路径
- 在执行前审查所有命令
许可证
此MCP服务器根据MIT许可证发布。您可以根据许可条款自由使用、修改和分发它。