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 (30 seconds)

# 1. Install the server
pip install git+https://github.com/jcvalerio/moneywiz-mcp-server.git

# 2. Set up configuration
python setup_env.py

# 3. Add to Claude Desktop config (~/.../Claude/claude_desktop_config.json)
{
  "mcpServers": {
    "moneywiz": {
      "command": "python",
      "args": ["-m", "moneywiz_mcp_server"]
    }
  }
}

# 4. Restart Claude Desktop and ask: "Show me my MoneyWiz accounts"

✨ 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 (New!)

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

📋 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
Python 3.10+: Ensure Python is installed
Claude Desktop: Install Claude Desktop application

🛠️ Installation

Option 1: Install from Source (Recommended)

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

# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install with dependencies
pip install -e ".[dev,test]"

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

Option 2: Install from PyPI (When Available)

pip install moneywiz-mcp-server

⚙️ Configuration

Automatic Setup (Recommended)

# Run the setup script to automatically find and configure your MoneyWiz database
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

The configuration file is located at:

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

2. Add MCP Server Configuration

Choose one of these configurations:

Standard Installation

{
  "mcpServers": {
    "moneywiz": {
      "command": "python",
      "args": ["-m", "moneywiz_mcp_server"]
    }
  }
}

Virtual Environment (FastMCP Best Practice)

{
  "mcpServers": {
    "moneywiz": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "moneywiz_mcp_server.main"],
      "cwd": "/path/to/your/moneywiz-mcp-server"
    }
  }
}

With Custom Database Path (FastMCP Best Practice)

{
  "mcpServers": {
    "moneywiz": {
      "command": "python",
      "args": ["-m", "moneywiz_mcp_server.main"],
      "cwd": "/path/to/your/moneywiz-mcp-server",
      "env": {
        "MONEYWIZ_DB_PATH": "/path/to/your/MoneyWiz.sqlite",
        "MONEYWIZ_READ_ONLY": "true"
      }
    }
  }
}

3. Restart Claude Desktop

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

🧪 Testing

Test Database Connection

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)
python -m moneywiz_mcp_server

Test with Claude Desktop

Try these queries in Claude Desktop:

"Show me all my MoneyWiz accounts"
"Analyze my expenses for the last 3 months"
"What's my current savings rate?"

🛡️ 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

Financial Analytics

search_transactions - Search transactions with natural language time periods
analyze_expenses_by_category - Analyze spending patterns by category
analyze_income_vs_expenses - Compare income vs expenses with savings analysis

Advanced Analytics (Phase 3)

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

🔧 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
python -c "from moneywiz_mcp_server.config import Config; print(Config.from_env().database_path)"

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

Claude Desktop Connection Issues

Validate JSON syntax:

python -c "import json; print(json.load(open('claude_desktop_config.json')))"

Test exact command:
```
python -m moneywiz_mcp_server
```
Check file permissions:
```
ls -la "/path/to/your/MoneyWiz.sqlite"
```

Common Issues

"Database not found": Check MONEYWIZ_DB_PATH and use absolute paths
"Permission denied": Ensure file permissions and MoneyWiz isn't locking the file
"MCP server not responding": Restart Claude Desktop and check JSON syntax
"No data found": Ensure MoneyWiz has transaction data and is the correct database

🔒 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
├── 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
│   ├── server.py               # MCP server
│   ├── 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
python -m venv venv
source venv/bin/activate
pip install -e ".[dev,test]"
python setup_env.py

Run Tests

python -m pytest tests/ -v

Code Quality

# Linting
flake8 src/
mypy src/

# Formatting
black src/
isort src/

📄 License

MIT License - see LICENSE file for details.

🆘 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
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.