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 助手。