Actual MCP

🚀 實際預算MCP服務器

實際預算MCP服務器用於將實際預算與Claude和其他大語言模型助手集成，讓你可以通過自然語言與個人財務數據進行交互。

🚀 快速開始

實際預算MCP服務器允許你通過大語言模型，使用自然語言與來自實際預算的個人財務數據進行交互。它通過模型上下文協議（MCP）公開你的賬戶、交易和財務指標。

✨ 主要特性

資源

• 賬戶列表 - 瀏覽所有賬戶及其餘額
• 賬戶詳情 - 查看特定賬戶的詳細信息
• 交易歷史 - 訪問包含完整細節的交易數據

工具

• get-transactions - 按賬戶、日期、金額、類別或收款人檢索和過濾交易
• spending-by-category - 生成按類型分類的支出明細
• monthly-summary - 獲取每月的收入、支出和儲蓄指標
• balance-history - 查看賬戶餘額隨時間的變化

提示

• financial-insights - 根據你的財務數據生成洞察和建議
• budget-review - 分析你的預算合規情況並建議調整方案

📦 安裝指南

前提條件

• Node.js（v16或更高版本）
• 已安裝並配置好實際預算
• Claude桌面版或其他支持MCP的客戶端

安裝步驟

1. 克隆倉庫：

git clone https://github.com/s-stefanov/actual-mcp.git
cd actual-mcp

2. 安裝依賴：

npm install

3. 構建服務器：

npm run build

4. 配置環境變量（可選）：

# 實際預算數據目錄的路徑（默認：~/.actual）
export ACTUAL_DATA_DIR="/path/to/your/actual/data"

# 如果使用遠程實際預算服務器
export ACTUAL_SERVER_URL="https://your-actual-server.com"
export ACTUAL_PASSWORD="your-password"

# 要使用的特定預算（可選）
export ACTUAL_BUDGET_SYNC_ID="your-budget-id"

💻 使用示例

與Claude桌面版配合使用

要在Claude桌面版中使用此服務器，需將其添加到Claude配置中：

在MacOS上：

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

在Windows上：

code %APPDATA%\Claude\claude_desktop_config.json

在配置中添加以下內容：

{
  "mcpServers": {
    "actualBudget": {
      "command": "npx",
      "args": ["-y", "actual-mcp"],
      "env": {
        "ACTUAL_DATA_DIR": "/path/to/your/actual/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

{
  "mcpServers": {
    "actualBudget": {
      "command": "docker",
      "args": ["run", "-it", "--rm", "-p", "3000:3000", "sstefanov/actual-mcp:latest"],
      "env": {
        "ACTUAL_DATA_DIR": "/path/to/your/actual/data",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id"
      }
    }
  }
}

保存配置後，重啟Claude桌面版。

示例查詢

連接成功後，你可以向Claude提出以下問題：

• "我當前的賬戶餘額是多少？"
• "顯示我上個月按類別劃分的支出情況"
• "我一月份在食品雜貨上花了多少錢？"
• "我過去三個月的儲蓄率是多少？"
• "分析我的預算並建議改進的方面"

🔧 技術細節

開發

若要在開發過程中實現自動重建，可以運行：

npm run watch

測試與實際預算的連接

要驗證服務器是否能連接到你的實際預算數據，可以運行：

node build/index.js --test-resources

調試

由於MCP服務器通過標準輸入輸出進行通信，調試可能具有一定挑戰性。你可以使用MCP檢查器：

npx @modelcontextprotocol/inspector node build/index.js

項目結構

• index.ts - 主服務器實現
• types.ts - API響應和參數的類型定義
• prompts.ts - 用於大語言模型交互的提示模板
• utils.ts - 用於日期格式化等的輔助函數

📄 許可證

本項目採用MIT許可證。

🤝 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。