Moneywiz MCP

🚀 MoneyWiz MCP 服務器

這是一個用於訪問 MoneyWiz 數據庫數據的 MCP（模型上下文協議）服務器。該服務器允許 ChatGPT、Claude 等支持 MCP 的客戶端查詢你的 MoneyWiz 財務數據，分析收支趨勢，獲取儲蓄建議，計算淨資產，並查看全面的財務統計信息。

🚀 快速開始

安裝

1. 克隆此倉庫：

git clone <repository-url>
cd moneywiz-mcp

2. 構建服務器：

go build -o moneywiz-mcp ./cmd/main.go

3. 導出你的 MoneyWiz 數據庫：
   • 打開 MoneyWiz 應用程序。
   • 轉到 設置 → 數據庫與導出 → 導出數據庫文件。
   • 這將創建一個文件夾（例如，iMoneyWiz-Data-Backup-2025_12_21-17_23），其中包含 SQLite 數據庫文件（ipadMoneyWiz.sqlite）。

運行服務器

可以通過命令行參數指定數據庫路徑來運行服務器：

./moneywiz-mcp -db /path/to/iMoneyWiz-Data-Backup-2025_12_21-17_23

或者，如果數據庫文件夾在當前目錄中：

./moneywiz-mcp -db ./iMoneyWiz-Data-Backup-2025_12_21-17_23

服務器將自動在指定文件夾中查找 ipadMoneyWiz.sqlite。

⚠️ 重要提示

你需要先從 MoneyWiz 導出數據庫（設置 → 數據庫與導出 → 導出數據庫文件）以獲取 SQLite 文件。

MCP 客戶端配置

要將此服務器與 MCP 客戶端（如 Claude Desktop）一起使用，請將其添加到你的 MCP 配置文件中。

快速設置（推薦）

運行設置腳本：

./setup.sh

這將自動使用正確的路徑配置 Claude Desktop。

手動配置

Claude Desktop 配置

{
  "mcpServers": {
    "moneywiz": {
      "command": "moneywiz-mcp/moneywiz-mcp",
      "args": ["-db", "moneywiz-mcp/iMoneyWiz-Data-Backup-2025_12_21-17_23"]
    }
  }
}

⚠️ 重要提示

請將路徑替換為你實際的絕對路徑。

更新配置後：

1. 完全退出 Claude Desktop（⌘Q）。
2. 重新打開 Claude Desktop。
3. MCP 服務器應會自動連接。

有關詳細的設置說明，請參閱 SETUP.md。

✨ 主要特性

• 列出賬戶：獲取所有賬戶的餘額和貨幣信息。
• 獲取賬戶餘額：檢索特定賬戶的餘額。
• 列出交易記錄：查看最近的交易記錄，可選擇按賬戶進行過濾。
• 列出類別：獲取所有支出/收入類別。
• 分析支出趨勢：按類別和時間段（月/年）分析支出趨勢。
• 分析收入趨勢：按類別和時間段（月/年）分析收入趨勢。
• 獲取儲蓄建議：根據收入與支出情況，提供個性化的儲蓄建議。
• 計算淨資產：從所有賬戶計算總淨資產（資產減去負債）。
• 獲取財務統計信息：從所有歷史數據中獲取全面的財務統計信息。

💻 使用示例

可用工具

list_accounts

列出 MoneyWiz 中的所有賬戶及其餘額和貨幣信息。

參數：無

示例：

{
  "name": "list_accounts",
  "arguments": {}
}

get_account_balance

按賬戶 ID 獲取特定賬戶的餘額。

參數：

• account_id（整數，必需）：賬戶的 ID

示例：

{
  "name": "get_account_balance",
  "arguments": {
    "account_id": 249
  }
}

list_transactions

列出最近的交易記錄，可選擇按賬戶 ID 進行過濾。

參數：

• account_id（整數，可選）：用於過濾交易記錄的賬戶 ID。如果未提供，則返回所有交易記錄。
• limit（整數，可選）：返回的最大交易記錄數（默認值：50）

示例：

{
  "name": "list_transactions",
  "arguments": {
    "account_id": 249,
    "limit": 20
  }
}

list_categories

列出 MoneyWiz 中的所有類別。

參數：無

示例：

{
  "name": "list_categories",
  "arguments": {}
}

analyze_spending_trends

按類別和時間段分析支出趨勢。按月份或年份對支出進行分組，並提供類別細分。

參數：

• group_by（字符串，可選）：按 "month" 或 "year" 分組（默認值："month"）
• months（整數，可選）：要分析的月數（默認值：6）

示例：

{
  "name": "analyze_spending_trends",
  "arguments": {
    "group_by": "month",
    "months": 6
  }
}

返回值：支出趨勢數組，包含：

• period：時間段（YYYY-MM 或 YYYY）
• total_spending：該時間段的總支出
• transaction_count：交易記錄數
• by_category：類別名稱到支出金額的映射

analyze_income_trends

按類別和時間段分析收入趨勢。按月份或年份對收入進行分組，並提供類別細分。

參數：

• group_by（字符串，可選）：按 "month" 或 "year" 分組（默認值："month"）
• months（整數，可選）：要分析的月數（默認值：6）

示例：

{
  "name": "analyze_income_trends",
  "arguments": {
    "group_by": "year",
    "months": 12
  }
}

返回值：收入趨勢數組，包含：

• period：時間段（YYYY-MM 或 YYYY）
• total_income：該時間段的總收入
• transaction_count：交易記錄數
• by_category：類別名稱到收入金額的映射

get_savings_recommendations

分析收入與支出情況，並獲取個性化的儲蓄建議。根據你的財務模式提供可行的建議。

參數：

• months（整數，可選）：要分析的月數（默認值：6）

示例：

{
  "name": "get_savings_recommendations",
  "arguments": {
    "months": 6
  }
}

返回值：儲蓄分析結果，包含：

• period：分析時間段描述
• total_income：該時間段的總收入
• total_spending：該時間段的總支出
• net_savings：淨儲蓄（收入 - 支出）
• savings_rate：儲蓄率（百分比）
• average_monthly_income：平均每月收入
• average_monthly_spending：平均每月支出
• top_spending_categories：前 5 大支出類別及其百分比
• recommendations：建議數組，包含：
  • type："warning"、"suggestion" 或 "positive"
  • title：建議標題
  • description：詳細建議
  • priority："high"、"medium" 或 "low"
  • impact：潛在節省金額

calculate_net_worth

從所有賬戶計算總淨資產。彙總所有賬戶餘額（資產減去負債）。

參數：無

示例：

{
  "name": "calculate_net_worth",
  "arguments": {}
}

返回值：淨資產計算結果，包含：

• total_assets：所有正賬戶餘額的總和
• total_liabilities：所有負賬戶餘額的總和（正值）
• net_worth：總資產減去總負債
• account_count：包含的賬戶數
• by_currency：按貨幣細分的淨資產
• accounts：所有賬戶及其餘額的數組

get_financial_stats

從所有歷史數據中獲取全面的財務統計信息。提供概述指標和年度細分。

參數：無

示例：

{
  "name": "get_financial_stats",
  "arguments": {}
}

返回值：財務統計信息，包含：

• total_transactions：總交易記錄數（所有時間）
• income_transactions：收入交易記錄數
• expense_transactions：支出交易記錄數
• total_income：總收入（所有時間）
• total_spending：總支出（所有時間）
• net_savings：淨儲蓄（所有時間）
• average_transaction：平均交易金額
• largest_income：最大單筆收入交易
• largest_expense：最大單筆支出交易
• account_count：總賬戶數
• category_count：總類別數
• first_transaction_date：第一筆交易的日期
• last_transaction_date：最後一筆交易的日期
• date_range：格式化的日期範圍字符串
• by_year：年度統計信息映射，包含：
  • year：年份（YYYY）
  • income：該年的總收入
  • spending：該年的總支出
  • net_savings：該年的淨儲蓄
  • transaction_count：該年的交易記錄數

🔧 技術細節

數據庫結構

此服務器訪問 MoneyWiz SQLite 數據庫（ipadMoneyWiz.sqlite）。該數據庫使用 Core Data 的實體 - 屬性 - 值模型，其中大多數對象存儲在 ZSYNCOBJECT 表中，具有不同的實體類型（Z_ENT）：

• 實體 10、11、12、13、15、16：賬戶（各種類型）
• 實體 37、45、46、47：常規交易
• 實體 43：轉賬交易
• 實體 19：類別

重要注意事項

• 日期：交易日期存儲為 Core Data 時間戳（自 2001-01-01 UTC 以來的秒數），並自動轉換為 ISO 格式。
• 餘額：賬戶餘額存儲在 ZBALLANCE 中（注意是雙 L）。如果餘額為 0 或 NULL，則根據初始餘額 + 交易記錄計算。
• 交易記錄：收入交易的 ZAMOUNT1 為正值，支出交易的 ZAMOUNT1 為負值。
• 類別：類別通過 ZCATEGORYASSIGMENT 表與交易記錄關聯。

📚 詳細文檔

項目結構

moneywiz-mcp/
├── cmd/
│   └── main.go          # 主入口點
├── internal/
│   ├── database/        # 數據庫訪問層
│   │   └── database.go
│   └── server/          # MCP 服務器實現
│       └── server.go
├── go.mod
└── README.md

構建

go build -o moneywiz-mcp ./cmd/main.go

依賴項

• github.com/mark3labs/mcp-go - MCP 服務器庫
• github.com/mattn/go-sqlite3 - SQLite 驅動

📄 許可證

有關詳細信息，請參閱 LICENSE 文件。