Actual Budget MCP Server

讓 Claude 幫你記帳！這是一個 Model Context Protocol (MCP) 伺服器，讓 AI 助手可以與你的 Actual Budget 互動。

功能

透過自然語言與 Claude 對話來管理你的預算：

• 📝 記帳 - 「幫我記帳，今天在全聯花了 $350 買日用品」

• 💰 查詢餘額 - 「我的現金帳戶還有多少錢？」

• 📊 預算追蹤 - 「這個月餐飲花了多少？還剩多少預算？」

• 🔍 搜尋交易 - 「上個月在 Costco 的消費有哪些？」

• 📈 支出分析 - 「幫我分析這個月的支出分佈」

支援的工具

快速開始

前置需求

• 運作中的 Actual Budget 伺服器

• 密碼認證（OpenID 用戶需同時啟用密碼登入）

• Docker（用於部署）

1. 取得 Budget Sync ID

在 Actual Budget 中：

1. 進入 Settings

2. 點擊 Show advanced settings

3. 複製 Sync ID

2. 設定環境變數

編輯 .env：

3. 使用 Docker 部署

或使用 Docker Compose：

4. 連接到 Claude

在 claude.ai 中設定 Connector：

1. 進入 Settings → Connectors

2. 點擊 Add Connector

3. 選擇 MCP

4. 輸入 URL：http://your-server:3000/mcp

TrueNAS Scale 部署

使用 Custom App

1. 在 TrueNAS Scale 中，進入 Apps → Discover Apps → Custom App

2. 設定如下：

   Application Name: actual-budget-mcp

   Image Repository: 你的 Docker registry 或本地建置

   Container Images:

   • Image: actual-budget-mcp:latest

   Container Environment Variables:

   ACTUAL_SERVER_URL=http://actual-budget:5006 ACTUAL_PASSWORD=your-password ACTUAL_BUDGET_ID=your-sync-id

   Networking:

   • Port: 3000 → 3000 (TCP)

   Storage:

   • Host Path: /mnt/your-pool/actual-mcp-cache

   • Mount Path: /data/actual-cache

3. 如果 Actual Budget 也在 TrueNAS 上，確保它們在同一個網路中。

與現有 Actual Budget 整合

如果你的 Actual Budget 已經部署在 TrueNAS：

本地開發

API 端點

使用範例

設定好 Connector 後，你可以這樣與 Claude 對話：

故障排除

連線失敗

1. 確認 Actual Budget 伺服器正在運行

2. 檢查 ACTUAL_SERVER_URL 是否正確

3. 如果使用 Docker 網路，確認容器名稱正確

認證失敗

1. 確認密碼正確

2. 如果使用 OpenID，確保同時啟用密碼登入：

   // config.json { "allowedLoginMethods": ["password", "openid"] }

Budget 找不到

1. 確認 ACTUAL_BUDGET_ID 是正確的 Sync ID

2. Sync ID 在 Actual Budget 的 Settings → Show advanced settings 中

加密錯誤

如果 budget 有啟用端對端加密，需要設定 ACTUAL_ENCRYPTION_PASSWORD

授權

MIT License

相關資源

• Actual Budget

• Actual Budget API 文件

• Model Context Protocol

• MCP TypeScript SDK