Hledger MCP

🚀 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：底层会计软件。
• 模型上下文协议：协议规范。
• Claude Desktop：支持 MCP 服务器的 AI 助手。