JUHE API Marketplace
jcvalerio avatar
MCP Server

MoneyWiz MCP Server

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

0
GitHub Stars
8/23/2025
Last Updated
MCP Server Configuration
1{
2 "name": "moneywiz",
3 "command": "python",
4 "args": [
5 "-m",
6 "moneywiz_mcp_server"
7 ]
8}
JSON8 lines

README Documentation

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

  1. Validate JSON syntax:

    python -c "import json; print(json.load(open('claude_desktop_config.json')))"
    
  2. Test exact command:

    python -m moneywiz_mcp_server
    
  3. 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

🤝 Contributing

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

Quick Install

Quick Actions

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source