Wealthfolio MCP Server

A Model Context Protocol (MCP) server that provides AI-powered portfolio analysis for Wealthfolio through Claude Desktop.

Version 2.0.0 - Production Ready ✅

🚀 Quick Start (3 commands)

git clone <repository-url> WFmcp && cd WFmcp
uv sync
uv run python setup.py  # Auto-configures everything

Then restart Claude Desktop. That's it!

---

✨ Nouveautés v2.0.0

• 🏠 Module Immobilier - 6 nouvelles fonctions pour analyser votre patrimoine immobilier
• 📊 Analyse par comptes - Regroupement par catégories (Investissement, Retraite, etc.)
• 🐛 Corrections majeures - Portfolio summary inclut maintenant l'immobilier
• 🛡️ 100% robuste - Fonctionne avec ou sans addon Real Estate
• 🧪 17 tests - Couverture complète et validation automatique

📚 Documentation:

• 🚀 Quick Start Guide - Démarrage en 5 minutes
• 📋 Changelog - Toutes les nouveautés
• 🔧 Corrections - Bugs corrigés
• 🛡️ Robustness - Guide de robustesse

---

Overview

This MCP server enables Claude to directly query and analyze your Wealthfolio portfolio data, providing natural language insights into your investments, asset allocation, portfolio performance, and real estate holdings.

14 outils MCP disponibles - Compatible avec ou sans addon Real Estate

Features

Financial Portfolio

• Portfolio Summary: Get total portfolio value and asset allocation breakdown
• Holdings Detail: Detailed list of all financial products with quantities, prices, valuations, gains/losses, and diversification analysis - essential for investment advice
• SQL Queries: Execute custom SELECT queries on your Wealthfolio database
• Natural Language Interface: Ask Claude about your portfolio in plain English

Real Estate Module

• Property Management: Track residential and commercial real estate properties
• Mortgage Analysis: Monitor loans with detailed amortization schedules
• Net Worth Calculation: Combined view of financial assets and real estate
• Property Valuation History: Track property values over time
• Early Payment Simulation: Calculate savings from accelerated mortgage payments

Write Operations

• Create Activities: Add new transactions (buy, sell, dividend, etc.)
• Create Assets: Add new securities to track
• Opening Positions: Bootstrap existing portfolios without manual transaction entry
• Data Import: Bulk import portfolio positions from CSV/Excel
• Database Updates: Execute validated INSERT/UPDATE/DELETE queries

Data Management

• Quote Fetching: Automatically download and update price data from Yahoo Finance
  • Batch updates for multiple symbols
  • Historical data backfill
  • Configurable date ranges and intervals
  • Saves time and tokens by automating price updates

Installation

Prerequisites

• Python 3.12 or higher
• uv package manager
• Wealthfolio installed with portfolio data
• Claude Desktop

Automated Setup (Recommended)

The easiest way to install and configure the MCP server:

# 1. Clone the repository
cd ~/dev  # or any folder you prefer (Windows: cd C:\Users\YourName\dev)
git clone <repository-url> WFmcp
cd WFmcp

# 2. Install dependencies
uv sync

# 3. Run the setup wizard (auto-detects paths and configures Claude Desktop)
uv run python setup.py

The setup script will:

• ✓ Automatically detect your OS
• ✓ Find your Wealthfolio database
• ✓ Locate Claude Desktop config file
• ✓ Configure everything for you
• ✓ Provide clear next steps

Then just restart Claude Desktop and you're done!

Manual Setup

If you prefer to configure manually, see SETUP.md for:

• Platform-specific paths (Windows/macOS/Linux)
• Complete configuration examples
• Troubleshooting tips

Usage

Once configured, ask Claude questions about your portfolio:

Portfolio Analysis

• "What's my total portfolio value?"
• "Show me my asset allocation"
• "Give me detailed information about all my holdings with current prices and gains"
• "How many accounts do I have?"
• "What are my largest holdings?"
• "Show me recent transactions"
• "Analyze my portfolio diversification and suggest improvements"

Real Estate Analysis

• "Show me all my real estate properties"
• "What's my total net worth including real estate?"
• "List all my mortgage loans"
• "Calculate the amortization schedule for my mortgage"
• "What would happen if I make a 10,000 EUR early payment next month?"
• "What's my loan-to-value ratio?"
• "Show me the valuation history for my Paris apartment"

Quote Management

• "Update the quotes for all my portfolio assets"
• "Fetch the latest prices for AAPL, MSFT, and GOOGL"
• "Download historical quotes for the past 90 days"
• "Update quotes with weekly data for the past year"

Transaction Management

• "Create a buy transaction for 100 shares of AAPL at $150"
• "Add a new asset: Tesla (TSLA) stock"
• "Record a dividend payment of $50 from VTI"

Testing

Run the test suite to verify functionality:

# Test database read operations
uv run python tests/test_database.py

# Test real estate module (read-only)
uv run python tests/test_real_estate.py

# Test write operations (CAUTION: modifies database)
uv run python tests/test_write_operations.py

# Test quote fetching (requires internet connection)
uv run python tests/test_quote_fetching.py

Note: Set the DB_PATH environment variable before running tests, or create a .env file with your database path.

Project Structure

WFmcp/
�� mcp_server.py          # Main MCP server implementation
�� tests/
   �� __init__.py
   �� test_database.py   # Database query tests
�� CLAUDE.md              # Development guide for Claude Code
�� Roadmap.md             # Strategic direction and planned features
�� Backlog.md             # Detailed feature backlog and tasks
�� README.md              # This file
�� pyproject.toml         # Python dependencies
�� .gitignore

Documentation

• CLAUDE.md: Technical documentation for development with Claude Code
• Roadmap.md: High-level strategic direction and quarterly goals
• Backlog.md: Detailed feature backlog with prioritization
• Write Operations Guide: Complete guide to using write operations (create activities, assets, etc.)
• History Reconstruction: Design document for bootstrapping portfolio tracking without complete history

Contributing

Contributions are welcome! Please:

1. Check the Backlog.md for open tasks
2. Review the Roadmap.md for strategic direction
3. Create an issue to discuss significant changes
4. Submit pull requests with tests

Security

Data Protection

• Your data never leaves your local machine
• The server communicates with Claude Desktop via stdio (no network access)
• All operations are local to your computer

Write Operation Safeguards

• Validation: All inputs are validated before database writes
• Confirmation Required: Destructive operations require explicit confirmation
• Forbidden Operations: DROP and TRUNCATE commands are blocked
• Account/Asset Checks: Verifies referenced entities exist before creating activities
• Date Validation: Ensures proper date formats
• Rollback on Error: Failed operations don't leave partial data

Best Practices

• Backup Your Database: Before using write operations, backup your Wealthfolio database
• Test First: Use the test suite to verify operations work as expected
• Review Changes: Check data in Wealthfolio after creating activities
• Start Small: Test with a few positions before bulk operations

Read Operations

• SELECT queries with intelligent limits:
  • 5000 rows for quotes table (sufficient for 10+ years of daily data)
  • 200 rows for other tables
• Results show truncation warning if limit exceeded
• No destructive operations possible with read-only tools

License

[Your chosen license]

Acknowledgments

• Built for Wealthfolio
• Uses Model Context Protocol
• Powered by Claude

Support

For issues or questions:

• Review CLAUDE.md for technical details
• Check existing issues
• Create a new issue with details about your setup and problem