MoneyWiz MCP Server

A Model Context Protocol (MCP) server that provides AI assistants like Claude with secure, read-only access to your MoneyWiz financial data for natural language queries and financial analytics.

🚀 Quick Start

# 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

See Claude Desktop Setup below for the exact JSON configuration.

Related MCP server: Wordware MCP

✨ What You Can Do

Ask Claude natural language questions about your finances:

💰 Account & Transaction Management

• "Show me all my MoneyWiz accounts with their balances"

• "Get details for my checking account including recent transactions"

• "Search my transactions from last month in the Groceries category"

📊 Expense Analytics

• "Analyze my expenses for the last 3 months by category"

• "What's my savings rate this year?"

• "Which spending category impacts my finances the most?"

💡 Advanced Analytics

• "Give me personalized savings recommendations with 25% target rate"

• "Analyze my spending trends over the last 6 months"

• "Show me category trends for my top 5 spending categories"

• "Track my income vs expense trends for financial health"

📅 Scheduled Transactions & Recurring Payments

• "Show me all my scheduled transactions"

• "What recurring payments do I have coming up?"

• "Analyze how my next salary covers my commitments"

• "When will my subscriptions and loans end?"

💵 Budget Management

• "Show me all my budgets with spending status"

• "Am I on track with my monthly budgets?"

• "Compare my budgeted amounts vs actual spending"

• "Which budgets are at risk of going over?"

📋 Prerequisites

• macOS: MoneyWiz MCP Server only supports macOS (MoneyWiz is only available on Apple platforms)

• MoneyWiz App: Install and set up MoneyWiz with some financial data

• uv: Install the uv package manager — it manages Python automatically, no separate Python install required

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

• Claude Desktop: Install Claude Desktop application

No system Python required. uv downloads and manages Python 3.12 automatically when you run uv sync.

🛠️ Installation

# 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

📌 Stable Releases and Rollback

For day-to-day use, prefer a tagged stable release once one is published. This keeps your Claude Desktop setup on known-good behavior while new roadmap work continues.

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

To upgrade intentionally, read the release notes first, then check out the desired version:

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

To roll back, return to the previous known-good tag and restart Claude Desktop:

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

The Claude Desktop configuration below remains compatible with pinned source checkouts as long as the checkout directory does not move. See Releasing for the versioning policy and maintainer checklist.

⚙️ Configuration

Automatic Setup (Recommended)

uv run python setup_env.py

The setup script will:

• Search for MoneyWiz databases on your Mac

• Let you select the correct database

• Create a .env file with your configuration

• Provide next steps for testing

Manual Configuration

Create a .env file in the project root:

# 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

Finding Your MoneyWiz Database

MoneyWiz stores data in these locations on 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/

Search command:

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

🖥️ Claude Desktop Setup

1. Find Your Claude Desktop Config

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

2. Add MCP Server Configuration

Claude Desktop does not source your shell, so bare commands like python or uv won't be found. Use absolute paths in the configuration.

Option A: Source Checkout

Use this option if you cloned the repository and ran 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"
    }
  }
}

Get your absolute path:

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

The .venv/bin/python binary is self-contained — it does not require Python to be installed globally on your Mac.

The cwd field is required so the server can locate the .env file with your database path.

Option B: PyPI with uvx

Use this option if you want Claude Desktop to run the published package without a source checkout. Because there is no checkout-local .env file in this mode, provide the MoneyWiz database path through the env block.

First, find the absolute path to uv:

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

Then configure Claude Desktop. Pin the package version for stable behavior, and replace MONEYWIZ_DB_PATH with your actual SQLite database path.

{
  "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"
      }
    }
  }
}

If you prefer to use the newest published package instead of a pinned version, remove ==1.0.1. Pinned versions are recommended for day-to-day use.

3. Restart Claude Desktop

Completely quit and reopen Claude Desktop for changes to take effect.

🧪 Testing

Test Database Connection

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())
"

Test MCP Server

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

🛡️ Available Tools

Once configured, Claude will have access to these MoneyWiz tools:

Account Management

• list_accounts - List all accounts with balances and types

• get_account - Get detailed account information by ID

Transaction Management

• search_transactions - Search transactions with natural language time periods and filters

Financial Analytics

• analyze_expenses_by_category - Analyze spending patterns by category

• analyze_income_vs_expenses - Compare income vs expenses with savings analysis

Advanced Analytics

• get_savings_recommendations - Personalized savings optimization with actionable tips

• analyze_spending_trends - Statistical trend analysis with projections and insights

• analyze_category_trends - Multi-category trend comparison and growth analysis

• analyze_income_expense_trends - Income vs expense sustainability tracking

Scheduled Transactions & Recurring Payments

• get_scheduled_transactions - List all scheduled and recurring transactions

• analyze_salary_breakdown - Analyze how salary covers commitments

• get_commitments_ending_timeline - Track when subscriptions, loans, and recurring payments end

Budget Management

• get_budgets - List all budgets with spending status and percentages

• analyze_budget_performance - Analyze which budgets are on track or at risk

• get_budget_vs_actual - Compare budgeted amounts vs actual spending by category

🔧 Technical Details

Architecture

• MCP Server: Modern FastMCP with decorator-based tool registration

• Database: Direct Core Data SQLite access (read-only by default)

• Analytics: Advanced savings optimization and trend analysis services

• Safety: Read-only mode by default with comprehensive input validation

• Integration: Seamless Claude Desktop integration with structured JSON responses

Database Support

• MoneyWiz 3: Full support for latest version including Setapp

• MoneyWiz 2: Legacy support

• Data: Accounts, transactions, categories, payees

• Size: Efficiently handles databases with thousands of transactions

🐛 Troubleshooting

Server Won't Start

# 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 Desktop Connection Issues

1. Validate JSON syntax:

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

2. Verify the .venv Python path exists:

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

3. Test the exact command Claude Desktop will run:

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

4. Check file permissions:

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

Common Issues

• "Database not found": Check MONEYWIZ_DB_PATH in .env and use absolute paths

• "Permission denied": Ensure file permissions and MoneyWiz isn't locking the file

• "MCP server not responding": Restart Claude Desktop and verify the .venv/bin/python path is correct

• "No data found": Ensure MoneyWiz has transaction data and is the correct database

• "command not found": Make sure you're using the absolute .venv/bin/python path, not bare python

🔒 Security

• Read-Only Mode: Database opened in read-only mode by default

• Local Access: Only accesses local database files

• No Network: No external network connections

• Privacy: All data processing happens locally

• Validation: All inputs validated before database queries

📁 Project Structure

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

🚀 Development

Setup Development Environment

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

Run Tests

uv run pytest tests/ -v

Code Quality

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

📄 License

MIT License - see LICENSE file for details.

🆘 Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes with tests

4. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

⚠️ Important: Always use read-only mode and back up your MoneyWiz database before first use.