SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI办公工具hledger-mcp

hledger-mcp

hledger-mcp 是一个本地 MCP（Model Context Protocol）服务器，用于让 AI 助手直接访问 HLedger 命令行会计工具的数据与功能。HLedger 是一款复式记账的纯文本会计软件，该服务器通过标准化协议使 AI 应用能够查询账户余额、生成财务报表、添加新分录并分析会计数据。它支持大多数 hledger CLI 命令，能够获取和遍历 include 引入的 journal 文件，并提供安全的 --read-only 只读模式。该工具已发布在 npm 上（@iiatlas/hledger-mcp），也可从 releases 获取可安装的 .mcpb 文件。

访问官网

工具介绍

用途

hledger-mcp 是一个本地 MCP 服务器，为 AI 助手（MCP 客户端）提供对 HLedger 会计数据与功能的直接访问。HLedger 是一款复式记账的纯文本会计工具，该服务器让 AI 应用能够通过标准化协议查询账户余额、生成财务报告、添加新分录并分析会计数据。

主要能力

服务器提供以下工具类别：

核心会计

  • Accounts：列出和查询账户名称与结构
  • Balance：生成余额报告，支持大量自定义选项
  • Register：查看交易登记簿和过账明细
  • Print：输出 journal 分录和交易

财务报表

  • Balance Sheet：生成资产负债表
  • Balance Sheet Equity：带权益明细的资产负债表
  • Income Statement：损益表
  • Cash Flow：现金流分析与报告
  • Stats：journal 数据的统计分析
  • Activity：账户活动与交易频率分析
  • Payees：列出并分析交易收款人
  • Descriptions：交易描述分析
  • Tags：查询和分析交易标签
  • Notes：列出唯一的交易备注和备忘字段
  • Files：列出 hledger 使用的数据文件

资源集成 自动将主 journal 以及 hledger files 报告的每个文件注册为 MCP 资源，客户端可浏览和检索源账本。

Journal 更新（写入工具）

  • Add Transaction：追加经过验证的新 journal 分录，支持 dry-run
  • Find Entry：定位匹配任意 hledger 查询的完整交易（含文件和行元数据）
  • Remove Entry：通过精确文本和位置安全删除交易，支持 dry-run
  • Replace Entry：验证后将现有交易替换为新内容
  • Import Transactions：从外部 journal 文件或其他支持格式安全批量导入分录
  • Close Books：生成结账/开账、留存收益或断言交易并安全追加
  • Rewrite Transactions：使用 hledger 的 rewrite 命令为匹配分录添加合成过账

Web UI

  • Start Web：以指定模式启动 hledger web，不阻塞 MCP 服务器（需要可选的 hledger-web 可执行文件）
  • List/Stop Web Instances：枚举会话期间启动的所有 web 服务器，优雅终止一个或全部

只读 MCP 会话始终以 view 模式运行 web 界面；写入启用的会话默认使用 add 权限，除非显式请求 allow: "edit"。

使用方式

前置要求

  • HLedger 必须已安装并在系统 PATH 中可访问（从 hledger.org 安装，用 hledger --version 验证）
  • Node.js v18 或更高版本

Claude Desktop 配置

通过 .mcpb 文件安装：从 releases 获取 .mcpb 文件，这是最简单的安装方式。

通过 NPM 安装：在 Claude Desktop 配置文件中添加配置。

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%/Claude/claude_desktop_config.json

将 /path/to/your/master.journal 替换为实际的 HLedger journal 文件路径。建议使用 master.journal，因为该工具支持通过 HLedger 现有的 include 语法引入的任何其他文件。

可通过可选标志切换写入行为：

  • --read-only：完全禁用 add-transaction 工具；所有写入尝试返回错误
  • --skip-backup：阻止服务器在追加到现有 journal 前创建 .bak 文件

标志可出现在 journal 路径之前或之后，两者默认均为 false。建议先启用 --read-only，直到熟悉该工具。

环境变量配置

  • HLEDGER_READ_ONLY：设为 true 强制只读模式
  • HLEDGER_SKIP_BACKUP：设为 true 禁用自动 .bak 备份
  • HLEDGER_EXECUTABLE_PATH：（可选）特定 hledger 二进制的绝对路径，若不在 PATH 中则覆盖自动检测
  • HLEDGER_WEB_EXECUTABLE_PATH：（可选）独立 hledger web 二进制的绝对路径

CLI 参数优先于环境变量。

其他 MCP 客户端 服务器通过 stdio 通信，期望 journal 文件路径作为第一个参数。

写入工具说明

  • hledger_add_transaction：接受结构化过账，用 hledger check 验证后追加新交易。启用 dryRun 可预览而不写入
  • hledger_remove_entry：通过精确文本和位置删除交易，用 hledger check 重新验证并遵循可选备份
  • hledger_replace_entry：将现有分录替换为新内容，保持间距整洁并在提交前执行验证
  • hledger_import：包装 hledger import，对 journal 的临时副本运行命令。提供一个或多个 dataFiles（journal、csv 等）和可选的 rulesFile；设置 dryRun 可在提交前检查差异。成功导入会创建带时间戳的 .bak 文件，除非 --skip-backup 生效
  • hledger_rewrite：在临时副本上运行 hledger rewrite，可为匹配交易指定一个或多个 addPostings 指令。使用 dryRun 仅预览差异，或 diff: true 在应用更改的同时包含补丁输出
  • hledger_close：通过 hledger close 生成结账/开账断言、留存收益或 clopen 交易。用 dryRun 预览生成的条目，满意后原子追加（可选备份）

所有写入工具都包含 dryRun 参数，可在写入前试用。

Web 工具说明

  • hledger_web：在空闲端口启动 hledger web UI/API，除非指定端口/socket。响应包含 instanceId，可用于后续跟踪或终止服务器
  • hledger_web_list：返回此 MCP 会话启动的每个活动 web 实例的元数据（PID、命令、基础 URL、访问模式等）
  • hledger_web_stop：通过 instanceId、pid 或 port 停止选定实例，或用 all=true 停止全部。可选择关闭信号（默认 SIGTERM）和超时

示例查询 配置后，可向 Claude 提出关于财务数据的自然语言问题：

  • "What's my current account balance?"
  • "Show me a balance sheet for last quarter"
  • "What were my expenses in the food category last month?"
  • "Generate an income statement for 2024"
  • "Who are my top payees by transaction volume?"
  • "Show me cash flow for the past 6 months"

工具参数 大多数工具支持常见 HLedger 选项：

  • 日期范围：--begin、--end、--period
  • 输出格式：txt、csv、json、html
  • 账户过滤：模式匹配和正则表达式支持
  • 计算模式：历史、累计、变化分析
  • 显示选项：平铺 vs 树形视图、排序、百分比

适用场景

适用于使用 HLedger 进行纯文本复式记账的用户，希望通过 AI 助手以自然语言查询账户余额、生成财务报表、分析交易数据，或安全地添加、修改、导入 journal 分录。也适合需要将会计数据集成到 MCP 兼容 AI 应用中的场景。

限制

  • 需要预先安装 HLedger 并使其在 PATH 中可访问
  • 需要 Node.js v18 或更高版本
  • Web UI 功能需要可选的 hledger-web 可执行文件；并非所有 hledger 安装都包含该二进制文件
  • 写入操作默认会创建 .bak 备份文件，除非使用 --skip-backup
  • 建议初次使用时启用 --read-only 模式

故障排除

  • "hledger CLI is not installed"：确保 HLedger 已安装并在 PATH 中。CLI 路径会尝试在常见位置自动查找；若不工作，可设置 HLEDGER_EXECUTABLE_PATH 环境变量
  • "hledger web command is failing"：并非所有 hledger 实例都包含 hledger-web 二进制文件，某些安装方式（如 .mcpb）难以找到它。建议先安装或找到当前安装位置，然后设置环境变量
  • "Journal file path is required"：服务器需要 journal 文件路径作为参数，检查配置确保包含且有效
  • Claude Desktop 连接问题：验证 journal 文件路径正确且可访问；检查配置文件语法是否为有效 JSON；配置更改后重启 Claude Desktop

许可证

MIT License（见 LICENSE）。参见 CONTRIBUTING.md 了解设置说明、编码标准以及本地测试和调试更改的提示。

同类工具

查看分类