MoneyWiz MCP Server

MoneyWiz MCP服务器

一个模型上下文协议（MCP）服务器，为克劳德等人工智能助手提供对MoneyWiz财务数据的安全、只读访问，用于自然语言查询和财务分析。

🚀 快速开始

# 1. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone and install
git clone https://github.com/jcvalerio/moneywiz-mcp-server.git
cd moneywiz-mcp-server
uv sync --all-extras

# 3. Find your MoneyWiz database
uv run python setup_env.py

# 4. Add to Claude Desktop config and restart

看 Claude桌面设置 下面是确切的JSON配置。

✨ 你能做什么

问克劳德关于你财务的自然语言问题：

💰 账户与交易管理

• “显示我的所有MoneyWiz账户及其余额”
• “获取我的支票账户的详细信息，包括最近的交易”
• “在杂货类别中搜索我上个月的交易”

📊 费用分析

• “按类别分析我过去3个月的支出”
• “我今年的储蓄率是多少？”
• “哪种支出类别对我的财务影响最大？”

💡 高级分析

• “以25%的目标利率为我提供个性化的储蓄建议”
• “分析我过去6个月的支出趋势”
• “显示我前5个支出类别的类别趋势”
• “跟踪我的收入与支出趋势，以保持财务健康”

📅 计划交易和经常性付款

• “显示我的所有计划交易”
• “我即将收到哪些定期付款？”
• “分析我的下一份薪水如何覆盖我的承诺”
• “我的订阅和贷款什么时候结束？”

💵 预算管理

• “显示我的所有预算和支出状态”
• “我的月度预算是否在正轨上？”
• “将我的预算金额与实际支出进行比较”
• “哪些预算有超支的风险？”

📋 先决条件

• macOS：MoneyWiz MCP服务器仅支持macOS（MoneyWiz仅在Apple平台上可用）
• MoneyWiz应用程序：安装并设置MoneyWiz，其中包含一些财务数据
• 紫外线：安装uv包管理器——它自动管理Python，不需要单独安装Python

  curl -LsSf https://astral.sh/uv/install.sh | sh

• 克劳德桌面版：安装Claude Desktop应用程序

不需要Python系统。 uv在运行时自动下载和管理Python 3.12 uv sync.

🛠️ 安装

# Clone the repository
git clone https://github.com/jcvalerio/moneywiz-mcp-server.git
cd moneywiz-mcp-server

# Install all dependencies (creates .venv with Python 3.12 automatically)
uv sync --all-extras

# Run setup to find your MoneyWiz database
uv run python setup_env.py

📌 稳定发布和回滚

对于日常使用，最好在发布后使用标记的稳定版本。这将使您的Claude Desktop设置保持已知的良好行为，同时继续进行新的路线图工作。

# From an existing source checkout
git fetch --tags
git checkout v1.0.0
uv sync --all-extras
uv run python setup_env.py

要有意升级，请先阅读发行说明，然后查看所需的版本：

git fetch --tags
git checkout vX.Y.Z
uv sync --all-extras

要回滚，请返回到之前已知的良好标记并重新启动Claude Desktop：

git fetch --tags
git checkout vPREVIOUS_VERSION
uv sync --all-extras

只要签出目录不移动，下面的Claude Desktop配置就与固定源代码签出保持兼容。看 释放 用于版本控制策略和维护者检查表。

⚙️ 配置

自动设置（推荐）

uv run python setup_env.py

安装脚本将：

• 在Mac上搜索MoneyWiz数据库
• 让您选择正确的数据库
• 创建一个 .env 使用您的配置文件
• 提供测试的后续步骤

手动配置

创建一个 .env 项目根目录中的文件：

# MoneyWiz Database Path
MONEYWIZ_DB_PATH=/Users/yourusername/Library/Containers/com.moneywiz.personalfinance-setapp/Data/Documents/.AppData/ipadMoneyWiz.sqlite

# Security Settings
MONEYWIZ_READ_ONLY=true

# Optional Settings
LOG_LEVEL=INFO
CACHE_TTL=300
MAX_RESULTS=1000

查找您的MoneyWiz数据库

MoneyWiz将数据存储在macOS上的以下位置：

# MoneyWiz 3 (most common)
~/Library/Containers/com.moneywiz.mac/Data/Documents/
~/Library/Containers/com.moneywiz.personalfinance/Data/Documents/
~/Library/Containers/com.moneywiz.personalfinance-setapp/Data/Documents/

# MoneyWiz 2
~/Library/Application Support/SilverWiz/MoneyWiz 2/

搜索命令：

find ~ -name "*.sqlite*" 2>/dev/null | grep -i moneywiz

🖥️ Claude桌面设置

1.查找您的Claude桌面配置

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

2.添加MCP服务器配置

Claude Desktop不会为你的shell提供源代码，所以像这样的裸命令 python 或 uv 找不到。在配置中使用绝对路径。

选项A：来源核查

如果您克隆了存储库并运行了 uv sync --all-extras.

{
  "mcpServers": {
    "moneywiz": {
      "command": "/ABSOLUTE/PATH/TO/moneywiz-mcp-server/.venv/bin/python",
      "args": ["-m", "moneywiz_mcp_server"],
      "cwd": "/ABSOLUTE/PATH/TO/moneywiz-mcp-server"
    }
  }
}

获取您的绝对路径：

echo "$(pwd)/.venv/bin/python"
# Example output: /Users/yourname/dev/moneywiz-mcp-server/.venv/bin/python

这 .venv/bin/python 二进制是自包含的——确实如此 不 需要在Mac上全局安装Python。

这 cwd 字段是必需的，以便服务器可以定位 .env 使用数据库路径创建文件。

选项B:PyPI uvx

如果您希望Claude Desktop在不签出源代码的情况下运行已发布的包，请使用此选项。因为当地没有收银台 .env 在此模式下，通过提供MoneyWiz数据库路径 env 块。

首先，找到绝对路径 uv:

command -v uv
# Example output: /Users/yourname/.local/bin/uv

然后配置Claude Desktop。固定包版本以获得稳定的行为，并替换 MONEYWIZ_DB_PATH 使用您的实际SQLite数据库路径。

{
  "mcpServers": {
    "moneywiz": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "x",
        "--from",
        "moneywiz-mcp-server==1.0.1",
        "moneywiz-mcp-server"
      ],
      "env": {
        "MONEYWIZ_DB_PATH": "/ABSOLUTE/PATH/TO/ipadMoneyWiz.sqlite",
        "MONEYWIZ_READ_ONLY": "true"
      }
    }
  }
}

如果您更喜欢使用最新发布的包而不是固定版本，请删除 ==1.0.1。建议日常使用固定版本。

3.重新启动克劳德桌面

完全退出并重新打开Claude Desktop以使更改生效。

🧪 测试

测试数据库连接

uv run python -c "
from moneywiz_mcp_server.config import Config
from moneywiz_mcp_server.database.connection import DatabaseManager
import asyncio

async def test():
    config = Config.from_env()
    print(f'Database: {config.database_path}')
    db = DatabaseManager(config.database_path)
    await db.initialize()
    print('✅ Database connection successful!')
    await db.close()

asyncio.run(test())
"

测试MCP服务器

# Start the server (should connect via stdio)
uv run python -m moneywiz_mcp_server

🛡️ 可用工具

配置后，Claude将可以访问这些MoneyWiz工具：

账户管理

• list_accounts -列出所有有余额和类型的账户
• get_account -按ID获取详细的帐户信息

事务管理

• search_transactions -使用自然语言时间段和过滤器搜索交易

财务分析

• analyze_expenses_by_category -按类别分析支出模式
• analyze_income_vs_expenses -通过储蓄分析比较收入与支出

高级分析

• get_savings_recommendations -个性化储蓄优化，提供可操作的提示
• analyze_spending_trends -带有预测和见解的统计趋势分析
• analyze_category_trends -多类别趋势比较和增长分析
• analyze_income_expense_trends -收入与支出可持续性跟踪

计划交易和经常性付款

• get_scheduled_transactions -列出所有计划和定期交易
• analyze_salary_breakdown -分析工资如何覆盖承诺
• get_commitments_ending_timeline -跟踪订阅、贷款和定期付款何时结束

预算管理

• get_budgets -列出所有预算，包括支出状态和百分比
• analyze_budget_performance -分析哪些预算正在按计划进行或面临风险
• get_budget_vs_actual -按类别比较预算金额与实际支出

🔧 技术细节

建筑

• MCP服务器：现代FastMCP，基于装饰器的工具注册
• 数据库：直接核心数据SQLite访问（默认情况下为只读）
• 分析：高级储蓄优化和趋势分析服务
• 安全：默认情况下为只读模式，具有全面的输入验证功能
• 整合：与结构化JSON响应无缝集成Claude Desktop

数据库支持

• MoneyWiz 3：完全支持最新版本，包括Setapp
• MoneyWiz 2：传统支持
• 数据：账户、交易、类别、收款人
• 尺寸：高效处理包含数千笔交易的数据库

🐛 故障排除

服务器无法启动

# Check if database file exists
ls -la "/path/to/your/MoneyWiz.sqlite"

# Test configuration
uv run python -c "from moneywiz_mcp_server.config import Config; print(Config.from_env().database_path)"

# Check server logs
uv run python -m moneywiz_mcp_server 2>&1 | head -20

Claude桌面连接问题

1. 验证JSON语法:

   python3 -c "import json; print(json.load(open('$HOME/Library/Application Support/Claude/claude_desktop_config.json')))"

1. 验证.vnv Python路径是否存在:

   ls -la /ABSOLUTE/PATH/TO/moneywiz-mcp-server/.venv/bin/python

1. 测试Claude Desktop将运行的确切命令:

   /ABSOLUTE/PATH/TO/moneywiz-mcp-server/.venv/bin/python -m moneywiz_mcp_server

1. 检查文件权限:

   ls -la "/path/to/your/MoneyWiz.sqlite"

常见问题

• “找不到数据库”：检查 MONEYWIZ_DB_PATH 在 .env 并使用绝对路径
• “权限被拒绝”：确保文件权限和MoneyWiz没有锁定文件
• “MCP服务器没有响应”：重新启动Claude Desktop并验证 .venv/bin/python 路径正确
• “未找到数据”：确保MoneyWiz有交易数据并且是正确的数据库
• “找不到命令”：确保你使用的是绝对值 .venv/bin/python 路径，不裸露 python

🔒 安全

• 只读模式：默认情况下，数据库以只读模式打开
• 本地访问：仅访问本地数据库文件
• 没有网络：无外部网络连接
• 隐私：所有数据处理都在本地进行
• 验证：在数据库查询之前验证所有输入

📁 项目结构

moneywiz-mcp-server/
├── README.md                    # This file
├── pyproject.toml              # Package configuration
├── uv.lock                     # Locked dependency versions
├── .python-version             # Python version pin (3.12.7)
├── setup_env.py               # Setup helper script
├── examples/                   # Configuration examples
│   ├── claude_desktop_config.json
│   ├── claude_desktop_config_venv.json
│   └── claude_code_config.json
├── src/moneywiz_mcp_server/    # Main package
│   ├── main.py                 # FastMCP server entry point
│   ├── config.py               # Configuration
│   ├── database/               # Database connection
│   ├── tools/                  # MCP tools
│   ├── services/               # Business logic
│   └── utils/                  # Utilities
└── tests/                      # Test suite

🚀 发展

设置开发环境

git clone https://github.com/jcvalerio/moneywiz-mcp-server.git
cd moneywiz-mcp-server
uv sync --all-extras
uv run python setup_env.py

运行测试

uv run pytest tests/ -v

代码质量

uv run ruff check .        # Linting
uv run ruff format .       # Formatting
uv run mypy src/           # Type checking
./scripts/check-ci.sh     # Full CI simulation

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🆘 支持

• 问题:
• 讨论:

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 通过测试进行更改
4. 提交拉取请求

看 贡献.md 详细指南。

______________________________________________________________________

⚠️ 重要：首次使用前，请始终使用只读模式并备份MoneyWiz数据库。