MCP Server Ledger

🚀 mcp-server-ledger：一個用於與Ledger CLI交互的MCP服務器

一個模型上下文協議（Model Context Protocol，MCP）服務器，用於與總賬本命令行界面工具交互。此服務器允許大型語言模型通過Ledger CLI工具查詢和分析您的財務數據，可幫助完成財務報告、預算分析和會計任務。

🚀 快速開始

此MCP服務器通過標準接口公開了Ledger CLI的功能，使AI助手能夠輕鬆幫助您完成財務報告、預算分析和會計任務。通過以下徽章和鏈接，您可以快速瞭解該項目：

✨ 主要特性

該服務器提供了以下工具，這些工具映射到Ledger CLI命令：

1. ledger_balance

   • 顯示帶有強大過濾選項的賬戶餘額
   • 輸入：查詢模式、日期範圍、顯示選項
   • 返回：格式化的餘額報告

2. ledger_register

   • 顯示詳細的交易記錄
   • 輸入：查詢模式、日期範圍、排序選項
   • 返回：格式化的註冊報告

3. ledger_accounts

   • 列出總賬文件中的所有賬戶
   • 輸入：可選查詢模式
   • 返回：匹配賬戶列表

4. ledger_payees

   • 列出交易中的所有付款人
   • 輸入：可選查詢模式
   • 返回：匹配的付款人列表

5. ledger_commodities

   • 列出使用的商品（貨幣）
   • 輸入：可選查詢模式
   • 返回：匹配的商品列表

6. ledger_print

   • 以總賬格式打印交易
   • 輸入：查詢模式、日期範圍
   • 返回：格式化的總賬條目

7. ledger_stats

   • 顯示關於總賬文件的統計信息
   • 輸入：可選查詢模式
   • 返回：總賬摘要統計信息

8. ledger_budget

   • 顯示預算分析
   • 輸入：查詢模式、日期範圍、報告週期
   • 返回：預算報告

9. ledger_raw_command

   • 執行原始的Ledger CLI命令
   • 輸入：命令參數作為字符串列表
   • 返回：命令輸出文本

📦 安裝指南

先決條件

• 必須安裝並配置好PATH環境變量的Ledger CLI
• 一個有效的總賬文件，其中包含您的財務數據

使用uv（推薦）

使用uv是最簡單的安裝和運行服務器的方式：

uv sync

💻 使用示例

基礎用法

創建新總賬文件

uv run mcp-server-ledger@latest ledger --new /path/to/file.ledger

添加日記條目

uv run mcp-server-ledger@latest ledger --add " liabilities:bank" 1000 USD "Initial deposit"

顯示賬戶餘額

uv run mcp-server-ledger@latest ledger --balance assets

高級用法

調試服務器

要調試服務器，請運行：

uv server --listen tcp://localhost:1234 mcp-server-ledger@latest --debug

本地開發

要在本地開發，請克隆倉庫並安裝依賴項：

git clone git@github.com:minhyeoky/mcp-server-ledger.git
cd mcp-server-ledger
npm install

然後啟動開發服務器：

uv server --listen tcp://localhost:1234 .

📚 詳細文檔

配置

該服務器需要指定總賬文件的路徑。可通過以下方式提供：

• 通過LEDGER_FILE環境變量
• 啟動服務器時通過命令行參數提供

使用Claude Desktop

將以下內容添加到您的claude_desktop_config.json中：

"mcpServers": {
  "ledger": {
    "command": "uv server --listen tcp://0.0.0.0:1234 mcp-server-ledger@latest",
    "options": {
      "LEDGER_FILE": "/path/to/your-ledger-file.ledger"
    }
  }
}

⚠️ 安全注意事項

⚠️ 重要提示

• 避免將敏感的財務數據暴露在不安全的網絡中。
• 確保總賬文件的安全性，防止未經授權的訪問。

📄 許可證

該軟件受MIT許可證的保護。請參閱LICENSE瞭解詳細信息。