金大哥 - hledger-mcp MCP 详情

article

README

🚀 HLedger MCP 服务器

HLedger MCP 服务器是一个基于模型上下文协议（MCP）的服务器，它允许 AI 助手（MCP 客户端）直接访问 HLedger 会计数据并使用其功能。通过标准化协议，该服务器使 AI 应用程序能够查询账户余额、生成财务报告、添加新条目以及分析会计数据。

它支持大多数 hledger 命令行工具，能够获取和遍历 !include 引用的账本文件，并且提供安全的 --read-only 只读模式。希望你会觉得它很实用！

该项目已发布到 npm，包名为 @iiatlas/hledger-mcp，也可以从 releases 页面下载可安装的 .mcpb 文件。

🚀 快速开始

前提条件

HLedger：必须安装 HLedger 并将其添加到系统环境变量 PATH 中。
- 可从 hledger.org 进行安装。
- 安装完成后，可通过 hledger --version 命令验证安装是否成功。
Node.js：版本需为 v18 或更高。

配置与使用

Claude Desktop 配置

通过 .mcpb 文件安装：最简单的安装方式是从 releases 页面下载 .mcpb 文件进行安装。如果你更喜欢使用 npm，可参考以下方法。
通过 npm 安装：在 Claude Desktop 配置文件中添加以下内容：
- macOS：配置文件路径为 ~/Library/Application Support/Claude/claude_desktop_config.json。
- Windows：配置文件路径为 %APPDATA%/Claude/claude_desktop_config.json。

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": ["-y", "@iiatlas/hledger-mcp", "/path/to/your/master.journal"]
    }
  }
}

请将 /path/to/your/master.journal 替换为你实际的 HLedger 账本文件路径。如果有 master.journal 文件，推荐使用它，因为该工具支持使用 HLedger 现有的 !include 语法引入的其他文件。示例账本可参考 test/resources/master.journal。

配置选项

你可以使用可选标志来切换写入行为：

--read-only：完全禁用添加交易工具，所有写入尝试都会返回错误。
--skip-backup：阻止服务器在追加到现有账本之前创建 .bak 备份文件。

这些标志可以出现在账本文件路径之前或之后，两个选项的默认值均为 false。建议在熟悉该工具之前启用 --read-only 模式。以下是示例配置：

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": [
        "-y",
        "@iiatlas/hledger-mcp",
        "/path/to/your/master.journal",
        "--read-only"
      ]
    }
  }
}

环境变量

偏好通过环境变量进行配置的 MCP 客户端可以设置以下变量：

HLEDGER_READ_ONLY：设置为 true 可强制启用只读模式。
HLEDGER_SKIP_BACKUP：设置为 true 可禁用自动 .bak 备份。
HLEDGER_EXECUTABLE_PATH：（可选）如果 hledger 不在系统环境变量 PATH 中，可指定其绝对路径，该设置会覆盖自动检测。
HLEDGER_WEB_EXECUTABLE_PATH：（可选）指定独立的 hledger web 二进制文件的绝对路径（例如 hledger-web）。设置后，MCP 将使用该可执行文件而不是通过主二进制文件运行 hledger web。

读写切换与上述 CLI 标志相对应，如果同时提供了 CLI 参数和环境变量，CLI 参数将优先使用。

你也可以在 JSON 配置中使用环境变量替代 args。以下是一个示例：

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": ["-y", "@iiatlas/hledger-mcp", "/path/to/your/master.journal"],
      "env": {
        "HLEDGER_READ_ONLY": "true",
        "HLEDGER_EXECUTABLE_PATH": "/opt/homebrew/bin/hledger"
      }
    }
  }
}

其他 MCP 客户端

对于其他支持 MCP 的应用程序，可使用以下命令启动服务器：

npx @iiatlas/hledger-mcp /path/to/your/master.journal

服务器通过标准输入输出进行通信，并将账本文件路径作为第一个参数。

✨ 主要特性

核心会计功能

账户管理：列出并查询账户名称和结构。
余额报告：生成具有广泛自定义选项的余额报告。
交易记录：查看交易记录和过账详情。
账本输出：输出账本条目和交易信息。

财务报告生成

资产负债表：生成资产负债表报告。
资产负债表权益：包含权益详情的资产负债表报告。
损益表：生成利润与损失报表。
现金流量表：进行现金流量分析并生成报告。

数据分析功能

统计分析：对账本数据进行统计分析。
账户活动：分析账户活动和交易频率。
交易收款人：列出并分析交易收款人。
交易描述：对交易描述进行分析。
交易标签：查询并分析交易标签。
交易备注：列出唯一的交易备注和备忘录字段。
数据文件：列出 hledger 使用的数据文件。

资源集成功能

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

账本更新功能

添加交易：追加新的、经过验证的账本条目，支持可选的预运行模式。
查找条目：定位与任何 hledger 查询匹配的完整交易（包含文件和行元数据）。
删除条目：使用确切的文本和位置安全地删除交易，支持可选的预运行模式。
替换条目：在验证更改后，用新内容替换现有交易。
导入交易：安全地从外部账本文件或其他支持的格式导入批量条目。
结账操作：生成结账/开账、留存收益或断言交易，并安全地追加它们。
重写交易：使用 hledger 的重写命令向匹配的条目添加合成过账。

网页界面功能

你可以直接在 MCP 服务器中打开 hledger 网页界面！

启动网页界面：在不阻塞 MCP 服务器的情况下，以请求的模式启动 hledger web。
- 需要可选的 hledger-web 可执行文件。如果你的 hledger 二进制文件不识别 web 命令，请安装 hledger-web（通常是一个单独的包），或者将 MCP 服务器指向具有网页支持的可执行文件。
- 可设置 HLEDGER_WEB_EXECUTABLE_PATH 环境变量，强制 MCP 服务器使用专用的二进制文件（如 hledger-web）启动网页界面。
列出/停止网页实例：枚举会话期间启动的所有活动网页服务器，并优雅地终止一个或所有实例。

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

💻 使用示例

基础用法

配置完成后，你可以向 Claude 提出关于财务数据的自然语言问题，例如：

- "我当前的账户余额是多少？"
- "给我展示上一季度的资产负债表。"
- "上个月我在食品类别的支出是多少？"
- "生成 2024 年的损益表。"
- "按交易量列出我的主要收款人。"
- "给我展示过去 6 个月的现金流量。"

高级用法

写入工具

当服务器未处于 --read-only 模式时，以下工具可用于修改主账本：

hledger_add_transaction：接受结构化过账，并在使用 hledger check 验证后追加新交易。启用 dryRun 可在写入前预览条目。
hledger_remove_entry：根据确切的文本和位置删除交易，使用 hledger check 重新验证，并考虑可选的备份。
hledger_replace_entry：用新内容替换现有条目，保持格式整齐，并在提交前进行验证。
hledger_import：封装 hledger import 命令，对账本的临时副本运行该命令。提供一个或多个 dataFiles（账本、CSV 等）和可选的 rulesFile；设置 dryRun 可在提交前检查差异。成功导入后，除非启用了 --skip-backup，否则会创建带时间戳的 .bak 文件。
hledger_rewrite：在临时副本上运行 hledger rewrite 命令，允许你为匹配的交易指定一个或多个 addPostings 指令。使用 dryRun 进行仅查看差异的预览，或设置 diff: true 以在应用更改时包含补丁输出。
hledger_close：通过 hledger close 生成结账/开账断言、留存收益或结账/开账交易。使用 dryRun 预览生成的条目，满意后原子性地追加它们（可选备份）。

所有写入工具都包含一个 dryRun 参数，可在写入前进行“试用”。

网页工具

hledger_web：在空闲端口上启动 hledger 网页界面/API，除非提供了特定的端口或套接字。响应中包含一个 instanceId，可用于后续跟踪或终止服务器。
hledger_web_list：返回此 MCP 会话启动的每个活动网页实例的元数据（PID、命令、基本 URL、访问模式等）。
hledger_web_stop：根据 instanceId、pid 或 port 停止选定的实例，或使用 all=true 停止所有实例。你可以选择关闭信号（默认 SIGTERM）和超时时间。

当 MCP 服务器以只读模式运行时，每个网页实例将强制使用 allow: "view" 模式。否则，服务器默认使用 allow: "add" 模式，除非明确请求 allow: "edit"。

📚 详细文档

工具参数支持

大多数工具支持常见的 HLedger 选项，包括：

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

🔧 技术细节

从源代码构建

# 克隆仓库
git clone <repository-url>
cd hledger-mcp

# （可选）如果你使用 nvm，可使用指定版本
nvm use

# 安装依赖
npm install

# 构建服务器
npm run build

# 运行测试
npm run test

# 启动调试服务器
npm run debug

项目结构

src/
├── index.ts              # 主服务器入口点
├── base-tool.ts          # 基础工具类和实用程序
├── executor.ts           # 命令执行实用程序
├── journal-writer.ts     # 安全的账本写入操作
├── resource-loader.ts    # MCP 资源发现和加载
├── types.ts              # 共享类型定义
└── tools/                # 各个工具的实现
    ├── accounts.ts       # 列出账户名称和结构
    ├── activity.ts       # 账户活动分析
    ├── add.ts            # 添加新交易
    ├── balance.ts        # 余额报告
    └── ...               # 还有更多...

test/
├── resources/            # 测试账本文件
│   ├── master.journal    # 包含引用的示例主账本
│   ├── 01-jan.journal    # 月度账本文件
│   ├── 02-feb.journal
│   └── ...
├── *.test.ts            # 工具和实用程序的单元测试
└── ...

📄 许可证

本项目采用 MIT 许可证，详情请见 LICENSE。

贡献指南

有关设置说明、编码标准以及在本地测试和调试更改的提示，请参阅 CONTRIBUTING.md。欢迎提交问题和拉取请求！

hledger-mcp