HLedger MCP Server

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

它支持大多数hledger命令行指令，能够获取并遍历!include的日记文件，并且有一个安全的--read-only模式。希望您会发现它很有用！

已发布到npm作为@iiatlas/hledger-mcp，并且可以从发行版下载安装的.mcpb文件。

功能

HLedger MCP服务器通过以下工具提供了对HLedger财务报告能力的全面访问：

核心会计

• 账户 - 列出并查询账户名称和结构
• 余额 - 生成具有广泛定制选项的余额报告
• 登记簿 - 查看交易登记簿和记账详情
• 打印 - 输出日记条目和交易

财务报告

• 资产负债表 - 生成资产负债表报告
• 资产负债表权益 - 包含权益细节的资产负债表报告
• 损益表 - 利润与损失报表
• 现金流量 - 现金流量分析和报告

数据分析

• 统计 - 日记数据的统计分析
• 活动 - 账户活动和交易频率分析
• 收款人 - 列出并分析交易收款人
• 描述 - 交易描述分析
• 标签 - 查询并分析交易标签
• 备注 - 列出唯一的交易备注和备忘字段
• 文件 - 列出hledger使用的数据文件

资源集成

• 自动注册主日记和由hledger files报告的每个文件作为MCP资源，以便客户端可以浏览和检索来源账本

日记更新

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

网页界面

您可以在MCP服务器内直接打开hledger网页UI！

• 启动网页 - 在请求的模式下启动hledger web而不阻塞MCP服务器
  • 需要可选的hledger-web可执行文件。如果您的hledger二进制文件不识别web命令，请安装hledger-web（通常是单独的包），或者指向带有网络支持构建的MCP服务器。
  • 设置HLEDGER_WEB_EXECUTABLE_PATH以强制MCP服务器使用专用二进制文件（如hledger-web）来启动网页界面。
• 列出/停止网页实例 - 枚举会话期间启动的所有正在运行的网页服务器，优雅地终止一个或所有

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

演示

一般概述：

查询和添加新条目：

从日记数据创建工件：

先决条件

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

使用方法

Claude桌面配置

安装.mcpb文件

最简单的安装扩展方式是通过发行版提供的.mcpb文件。如果您更喜欢npm，可以使用下面的方法。

通过NPM安装

将以下内容添加到您的Claude桌面配置文件中：

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参数优先。

您也可以在json配置中的args位置使用环境变量。这里是一个示例：

{
  "mcpServers": {
    "hledger": {
      "command": "npx",
      "args": ["-y", "@iiatlas/hledger-m-mp", "/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

服务器通过stdio通信，并期望日记文件路径作为第一个参数。

写入工具

当服务器未处于--read-only模式时，这些工具可以修改主日记：

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

所有写入工具都包含一个dryRun参数，用于“试一试”再写入。

网页工具

• hledger_web 在空闲端口上启动hledger网页UI/API，除非提供了特定的端口/套接字。响应包括一个instanceId，可用于稍后跟踪或终止服务器。
• hledger_web_list 返回由此MCP会话启动的每个活跃网页实例的元数据（PID、命令、基础URL、访问模式等）。
• hledger_web_stop 通过instanceId、pid或port停止选定的实例，或通过all=true停止一切。您可以选择关闭信号（默认为SIGTERM）和超时。

当MCP服务器处于只读模式时，每个网页实例都被强制为allow: "view"。否则，服务器默认为allow: "add"，除非显式请求allow: "edit"。

示例查询

一旦配置好，您可以向Claude提出关于财务数据的自然语言问题：

• “我的当前账户余额是多少？”
• “显示上一季度的资产负债表”
• “上个月我在食品类别上的支出是多少？”
• “生成2024年的损益表”
• “按交易量计算，谁是我的主要收款人？”
• “显示过去6个月的现金流”

工具参数

大多数工具支持常见的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    # 包含includes的示例主日记
│   ├── 01-jan.journal    # 月度日记文件
│   ├── 02-feb.journal
│   └── ...
├── *.test.ts            # 工具和实用程序的单元测试
└── ...

故障排除

"hledger CLI未安装"

确保HLedger已安装并在PATH中可用：

hledger --version

hledger cli路径试图自动找到常见位置（参见hledger-path.ts:8）。如果这不起作用，您可以设置HLEDGER_EXECUTABLE_PATH环境变量到离散路径。

# 查找hledger安装路径
which hledger

"hledger web命令失败"

并非所有的hledger实例都包含hledger-web二进制文件。此外，某些安装方法（如.mcpb）很难找到它。如果您难以启动网页UI，我建议首先安装或查找当前安装：

# 查找hledger-web安装路径
which hledger-web

然后将其设置为环境变量。对于我的通过homebrew安装的情况，这是：

HLEDGER_WEB_EXECUTABLE_PATH=/opt/homebrew/bin/hledger-web

"需要日记文件路径"

服务器需要日记文件路径作为参数。检查您的配置以确保包含了一个有效的路径。

Claude桌面连接问题

1. 验证日记文件路径正确且可访问
2. 检查配置文件语法是否为有效JSON
3. 配置更改后重启Claude桌面

许可证

MIT许可证（参见LICENSE）

贡献

参见CONTRIBUTING.md以获取设置说明、编码标准以及本地测试和调试更改的提示。我们欢迎问题和拉取请求！

相关项目

• HLedger - 底层会计软件
• 模型上下文协议 - 协议规范
• Claude桌面 - 支持MCP服务器的AI助手