Wealthfolio MCP Server

# Wealthfolio MCP Server A Model Context Protocol (MCP) server that provides AI-powered portfolio analysis for [Wealthfolio](https://wealthfolio.app/) through Claude Desktop. **Version 2.0.0** - Production Ready ✅ []() []() []() ## 🚀 Quick Start (3 commands) ```bash 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](QUICKSTART.md) - Démarrage en 5 minutes - [📋 Changelog](CHANGELOG.md) - Toutes les nouveautés - [🔧 Corrections](CORRECTIONS.md) - Bugs corrigés - [🛡️ Robustness](ROBUSTNESS.md) - 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](https://github.com/astral-sh/uv) package manager - [Wealthfolio](https://wealthfolio.app/) installed with portfolio data - [Claude Desktop](https://claude.ai/download) ### Automated Setup (Recommended) The easiest way to install and configure the MCP server: ```bash # 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](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: ```bash # 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](CLAUDE.md)**: Technical documentation for development with Claude Code - **[Roadmap.md](Roadmap.md)**: High-level strategic direction and quarterly goals - **[Backlog.md](Backlog.md)**: Detailed feature backlog with prioritization - **[Write Operations Guide](docs/WRITE_OPERATIONS.md)**: Complete guide to using write operations (create activities, assets, etc.) - **[History Reconstruction](docs/HISTORY_RECONSTRUCTION.md)**: Design document for bootstrapping portfolio tracking without complete history ## Contributing Contributions are welcome! Please: 1. Check the [Backlog.md](Backlog.md) for open tasks 2. Review the [Roadmap.md](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](https://wealthfolio.app/) - Uses [Model Context Protocol](https://modelcontextprotocol.io/) - Powered by [Claude](https://claude.ai/) ## Support For issues or questions: - Review [CLAUDE.md](CLAUDE.md) for technical details - Check existing issues - Create a new issue with details about your setup and problem