# 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 ✅

[![Tests](https://img.shields.io/badge/tests-17%2F17%20passing-brightgreen)]()
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)]()
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)]()

## 🚀 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