moneywiz-mcp-server 1.0.1

Read-only MCP server for local MoneyWiz financial analytics

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.

✨ 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. You must use the absolute path to the Python binary inside .venv.

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

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.