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 文件。