Hledger MCP Docker

HLedger MCP Docker设置

此目录包含用于运行 hledger mcp Docker中的服务器。

你为什么想要这个？如果你不想在你的环境中安装NodeJS和NodeJS包，并且想保持hledger-mcp及其依赖项的自包含性。

用法

基本用法

使用日志文件运行（卷定义使容器内的路径与实际路径匹配，这样“hledger文件”等的输出就不会混淆模型）：

docker run -it --rm \
  -v /path/to/your/journals:/path/to/your/journals:ro \
  dastapov/hledger-mcp:alpine /path/to/your/journals/master.journal

只读模式（推荐）

docker run -it --rm \
  -v /path/to/your/journals:/path/to/your/journals:ro \
  dastapov/hledger-mcp:alpine /path/to/your/journals/master.journal --read-only

如果您想要写访问权限，请删除 :ro 从 -v 开关。如果不希望创建备份文件，请添加 --skip-backup

使用环境变量

docker run -it --rm \
  -v /path/to/your/journals:/path/to/your/journals:ro \
  -e HLEDGER_READ_ONLY=true \
  -e HLEDGER_SKIP_BACKUP=true \
  dastapov/hledger-mcp:alpine /path/to/your/journals/master.journal

具有Web界面

要使用hledger web，请暴露端口5000：

docker run -it --rm \
  -v /path/to/your/journals:/path/to/your/journals:ro \
  -p 5000:5000 \
  dastapov/hledger-mcp:alpine /path/to/your/journals/master.journal

Docker Compose

创建一个 docker-compose.yml 文件：

version: '3.8'

services:
  hledger-mcp:
    # For prebuilt image, use this instead:
    # image: dastapov/hledger-mcp:alpine
    build:
      context: .
      dockerfile: Dockerfile.alpine
    container_name: hledger-mcp
    volumes:
      # Mount your journal files (read-only recommended)
      - /path/to/your/journals:/path/to/your/journals:ro
    environment:
      - HLEDGER_READ_ONLY=true
      - NODE_ENV=production
    # Uncomment to expose web interface
    # ports:
    #   - "5000:5000"
    stdin_open: true
    tty: true
    command: ["/path/to/your/journals/master.journal", "--read-only"]

运行方式：

docker-compose up

Claude代码的配置

运行此命令以配置mcp服务器：

claude mcp add --transport stdio hledger -- docker run -i --rm -v /absolute/path/to/your/journals:/absolute/path/to/your/journals:ro dastapov/hledger-mcp:alpine /absolute/path/to/your/journals/master.journal --read-only

替换 /absolute/path/to/your/journals 日志文件的实际绝对路径。

开放代码配置

添加 ~/.config/opencode/opencode.json:

 "mcp": {
    "hledger": {
      "type": "local",
      "command": ["docker",
        "run",
        "-i",
        "--rm",
        "-v",
        "/absolute/path/to/your/journals:/absolute/path/to/your/journals:ro",
        "dastapov/hledger-mcp:alpine",
        "/absolute/path/to/your/journals/master.journal",
        "--read-only"
      ]
    }
  }

替换 /absolute/path/to/your/journals 日志文件的实际绝对路径。

故障排除

“找不到日志文件”

• 验证卷装载路径是否正确
• 确保日志文件存在于指定路径中
• 对卷装载使用绝对路径

“权限被拒绝”

• 检查主机系统上的文件权限
• 确保挂载的目录可读（如果不使用，则可写 --read-only)

Web界面不可访问

• 确保端口5000暴露在外： -p 5000:5000
• 检查是否安装了hledger web： docker run --rm hledger-mcp:alpine hledger-web --version

环境变量

• HLEDGER_READ_ONLY：设置为 true 强制只读模式
• HLEDGER_SKIP_BACKUP：设置为 true 禁用自动 .bak 备份
• HLEDGER_EXECUTABLE_PATH：hledger二进制文件的路径（默认：自动检测）
• HLEDGER_WEB_EXECUTABLE_PATH：hledger web二进制文件的路径（默认：自动检测）
• NODE_ENV：Node.js环境（默认值： production)
• LANG：系统区域设置（默认值： C.UTF-8)

可用的Dockerfiles

1. Dockerfile -完整构建

• 使用Stack从源代码构建hledger
• 确保hledger的最新版本
• 更大的图像大小（~2GB）
• 更长的构建时间（30-60分钟）
• 最适合：需要最新处理器功能的生产使用

2. Dockerfile.alpine -高山套餐

• 使用Alpine存储库中的预构建hledger
• 图像大小小得多（~200MB）
• 快速构建时间（2分钟）
• 可能有稍旧的hledger版本
• 最适合：快速设置、测试、开发

构建说明

使用完整版本：

docker build -t hledger-mcp:latest -f Dockerfile .

使用Alpine版本（建议快速入门）：

docker build -t hledger-mcp:alpine -f Dockerfile.alpine .

或者使用便利脚本 build.sh

资源

• hledger文件
• 模型上下文协议