AI导哈

会计数据服务器

HLedger MCP服务器是一个为AI助手提供会计数据访问和功能的协议服务器，支持查询账户余额、生成财务报告、添加新条目和数据分析。

  • by iiAtlas
  • TypeScript
  • 本地部署
  • 65 星标
  • 更新于
在 GitHub 查看 iiAtlas/hledger-mcp

使用说明

HLedger MCP服务器

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

它得到了大多数人的支持 hledger cli命令，获取遍历的能力 included日志文件和保险箱 --read-only 模式。我希望你觉得它有用！

发布于npm @iiatlas/hledger mcp，并且可作为可安装的 .mcpb 文件来自 发布.

特性

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

核心会计

  • 账户 -列出并查询帐户名称和结构
  • 平衡 -生成具有广泛自定义选项的余额报告
  • 注册 -查看交易登记和过账详细信息
  • 打印 -输出日记账分录和交易记录

财务报告

  • 资产负债表 -生成资产负债表报告
  • 资产负债表权益 -包含权益详情的资产负债表报告
  • 利润表 -损益表
  • 现金流 -现金流分析和报告

数据分析

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

资源整合

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

期刊更新

  • 增加交易 -添加新的、经过验证的日记账分录，并提供可选的模拟运行支持
  • 查找条目 -查找与任何hledger查询匹配的完整事务（包括文件和行元数据）
  • 删除条目 -使用交易的确切文本和位置安全删除交易，并可选择模拟运行
  • 替换条目 -验证更改后，将现有事务替换为新内容
  • 进口交易 -安全地从外部日志文件或其他支持的格式中摄取批量条目
  • 结账 -生成收盘/开盘、保留收益或断言交易，并安全地附加它们
  • 重写交易 -使用hledger的重写命令将合成帖子添加到匹配的条目中

网络界面

您可以直接在MCP服务器中打开hledger web UI！

  • 启动Web -发布 hledger web 在请求模式下，不阻塞MCP服务器
    • 需要可选 hledger-web 可执行.如果你 hledger 二进制无法识别 web 命令，安装 hledger-web （通常是单独的包）或将MCP服务器指向使用web支持构建的可执行文件。
    • 集 HLEDGER_WEB_EXECUTABLE_PATH 强制MCP服务器使用专用二进制文件（例如 hledger-web)用于启动web界面。
  • 列出/停止Web实例 -枚举会话期间启动的所有正在运行的web服务器，优雅地终止一个或所有服务器

只读MCP会话始终在中运行web界面 view 模式，而启用写入的会话默认为 add 权限，除非 allow: "edit" 是明确要求的。

演示

概述：

查询和添加新条目：

从日志数据创建工件：

先决条件

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

用法

Claude桌面配置

安装.mcpb文件

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

通过NPM安装

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

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %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参数为准。

您还可以使用环境变量来代替 args 在json配置中。以下是一个示例：

{
  "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

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

编写工具

当服务器不在时 --read-only 模式下，这些工具可以修改主日志：

  • hledger_add_transaction 接受结构化过账，并在验证后附加新交易 hledger check.启用 dryRun 无需书写即可预览条目。
  • hledger_remove_entry 按确切的文本和位置删除交易，并用重新验证 hledger check 并尊重可选备份。
  • hledger_replace_entry 将现有条目替换为新内容，保持间距整洁，并在提交前执行验证过程。
  • hledger_import 包裹 hledger import，对日志的临时副本运行该命令。提供一个或多个 dataFiles （日志、csv等）和可选 rulesFile；set dryRun 在提交之前检查差异。成功导入创建时间戳 .bak 文件除非 --skip-backup 是活跃的。
  • hledger_rewrite 跑 hledger rewrite 在临时副本上，允许您指定一个或多个 addPostings 匹配交易的说明。使用 dryRun 仅用于差异预览或 diff: true 将补丁输出与应用的更改一起包含在内。
  • hledger_close 通过以下方式生成收盘/开盘断言、保留收益或进行交易 hledger close.使用以下命令预览生成的条目 dryRun，然后在您满意后以原子方式附加它们（可选备份）。

所有写入工具都包括 dryRun 在写入之前，将参数设置为“试用”。

网络工具

  • hledger_web 除非提供了特定的端口/套接字，否则会在空闲端口上启动hledgerwebUI/API。该回复包括 instanceId 其可用于稍后跟踪或终止服务器。
  • hledger_web_list 返回此MCP会话启动的每个活动web实例的元数据（PID、命令、基本URL、访问模式等）。
  • hledger_web_stop 通过以下方式停止所选实例 instanceId, pid，或 port，或停止一切 all=true。您可以选择关机信号(SIGTERM 默认情况下）和超时。

当MCP服务器以只读模式运行时，每个web实例都必须 allow: "view"。否则，服务器默认为 allow: "add" 除非 allow: "edit" 是明确要求的。

查询示例

配置后，您可以向Claude自然语言提问有关您的财务数据的问题：

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

刀具参数

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

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

发展

从源头构建

# Clone the repository
git clone <repository-url>
cd hledger-mcp

# (Optional) If you have nvm, use this version
nvm use

# Install dependencies
npm install

# Build the server
npm run build

# Test
npm run test

# Run the debug server
npm run debug

项目结构

src/
├── index.ts              # Main server entry point
├── base-tool.ts          # Base tool classes and utilities
├── executor.ts           # Command execution utilities
├── journal-writer.ts     # Safe journal writing operations
├── resource-loader.ts    # MCP resource discovery and loading
├── types.ts              # Shared type definitions
└── tools/                # Individual tool implementations
    ├── accounts.ts       # List account names and structures
    ├── activity.ts       # Account activity analysis
    ├── add.ts            # Add new transactions
    ├── balance.ts        # Balance reports
    └── ...               # ...and many more

test/
├── resources/            # Test journal files
│   ├── master.journal    # Example master journal with includes
│   ├── 01-jan.journal    # Monthly journal files
│   ├── 02-feb.journal
│   └── ...
├── *.test.ts            # Unit tests for tools and utilities
└── ...

故障排除

“未安装hledger CLI”

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

hledger --version

hledger-cli路径尝试在公共位置自动找到（请参阅 hledger路径。ts：8).如果这不起作用，你可以设置 HLEDGER_EXECUTABLE_PATH 环境变量到离散路径。

# Find hledger installation path
which hledger

“hledger web命令失败”

并非所有hledger实例都包括 hledger-web 二元的。此外，一些安装方法（如 .mcpb)很难找到它。如果你很难启动web UI，我建议你先安装或找到当前的安装：

# Find hledger-web installation path
which hledger-web

然后将其设置为环境变量。对于我通过自制程序进行的安装，这是：

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

“日志文件路径是必需的”

服务器需要日志文件路径作为参数。检查您的配置，确保其中包含一个配置并且有效。

Claude桌面连接问题

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

许可证

MIT许可证（见 许可证)

贡献

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

相关项目

相关 MCP