HLedger MCP服务器
一种模型上下文协议（MCP）服务器，为AI助手（MCP客户端）提供直接访问 HLedger 会计数据和功能。该服务器使AI应用程序能够通过标准化协议查询账户余额、生成财务报告、添加新条目和分析会计数据。
它得到了大多数人的支持 hledger cli命令，获取遍历的能力 included日志文件和保险箱 --read-only 模式。我希望你觉得它有用！
特性
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" 是明确要求的。
演示
概述：
查询和添加新条目：
从日志数据创建工件： Artifact-Demo
先决条件
- 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；setdryRun在提交之前检查差异。成功导入创建时间戳.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
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 --versionhledger-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桌面连接问题
- 验证日志文件路径是否正确且可访问
- 检查配置文件语法是否为有效的JSON
- 配置更改后重新启动Claude Desktop
许可证
MIT许可证（见 许可证)
贡献
看 CONTRIBUTING.md 有关本地测试和调试更改的设置说明、编码标准和提示。我们欢迎问题和拉取请求！