# portfolio-mcp

A portfolio analysis MCP server powered by [mcp-refcache](https://github.com/l4b4r4b4b4/mcp-refcache) for building AI agent tools that handle financial data efficiently.

[![Tests](https://github.com/l4b4r4b4b4/portfolio-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/l4b4r4b4b4/portfolio-mcp/actions/workflows/ci.yml)
[![Coverage](https://img.shields.io/badge/coverage-81%25-green)](https://github.com/l4b4r4b4b4/portfolio-mcp)
[![Python](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

## Features

- **Portfolio Management**: Create, read, update, delete portfolios with persistent storage
- **Data Sources**: Yahoo Finance (stocks/ETFs), CoinGecko (crypto), Synthetic (GBM simulation)
- **Analysis Tools**: Returns, volatility, Sharpe ratio, Sortino ratio, VaR, drawdowns, correlations
- **Optimization**: Efficient Frontier, Monte Carlo simulation, weight optimization
- **Reference-Based Caching**: Large datasets cached via mcp-refcache to avoid context bloat

## Installation

### Using uv (recommended)

```bash
# Clone the repository
git clone https://github.com/l4b4r4b4b4/portfolio-mcp
cd portfolio-mcp

# Install dependencies
uv sync

# Run the server
uv run portfolio-mcp stdio
```

### Using pip

```bash
pip install portfolio-mcp
portfolio-mcp stdio
```

## Quick Start

### Connect to Claude Desktop

Add to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "portfolio-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/portfolio-mcp", "portfolio-mcp", "stdio"]
    }
  }
}
```

### Basic Usage

Once connected, you can use natural language to:

```
"Create a portfolio called 'tech_stocks' with AAPL, GOOG, and MSFT"
"Analyze the returns and volatility of my tech_stocks portfolio"
"Optimize my portfolio for maximum Sharpe ratio"
"Show me the efficient frontier with 20 points"
"Compare my portfolios by Sharpe ratio"
```

## Available Tools

### Portfolio Management (6 tools)
- `create_portfolio` - Create a new portfolio with symbols and weights
- `get_portfolio` - Retrieve portfolio details and metrics
- `list_portfolios` - List all stored portfolios
- `delete_portfolio` - Remove a portfolio
- `update_portfolio_weights` - Modify portfolio weights
- `clone_portfolio` - Create a copy with optional new weights

### Analysis Tools (8 tools)
- `get_portfolio_metrics` - Comprehensive metrics (return, volatility, Sharpe, Sortino, VaR)
- `get_returns` - Daily, log, or cumulative returns
- `get_correlation_matrix` - Asset correlation analysis
- `get_covariance_matrix` - Variance-covariance structure
- `get_individual_stock_metrics` - Per-asset statistics
- `get_drawdown_analysis` - Maximum drawdown and recovery analysis
- `compare_portfolios` - Side-by-side portfolio comparison

### Optimization Tools (4 tools)
- `optimize_portfolio` - Optimize weights (max Sharpe, min volatility, target return/vol)
- `get_efficient_frontier` - Generate efficient frontier curve
- `run_monte_carlo` - Monte Carlo simulation for portfolio analysis
- `apply_optimization` - Apply optimization and update stored portfolio

### Data Tools (8 tools)
- `generate_price_series` - Generate synthetic GBM price data
- `generate_portfolio_scenarios` - Create multiple scenario datasets
- `get_sample_portfolio_data` - Get sample data for testing
- `get_trending_coins` - Trending cryptocurrencies from CoinGecko
- `search_crypto_coins` - Search for crypto assets
- `get_crypto_info` - Detailed cryptocurrency information
- `list_crypto_symbols` - Available crypto symbol mappings
- `get_cached_result` - Retrieve cached large results by reference ID

## Architecture

```
portfolio-mcp/
├── app/
│   ├── __init__.py
│   ├── __main__.py      # Typer CLI entry point
│   ├── config.py        # Pydantic settings
│   ├── server.py        # FastMCP server setup
│   ├── storage.py       # RefCache-based portfolio storage
│   ├── models.py        # Pydantic models for I/O
│   ├── data_sources.py  # Yahoo Finance + CoinGecko APIs
│   └── tools/           # MCP tool implementations
│       ├── portfolio.py
│       ├── analysis.py
│       ├── optimization.py
│       └── data.py
└── tests/               # 163 tests, 81% coverage
```

## Reference-Based Caching

This server uses [mcp-refcache](https://github.com/l4b4r4b4b4/mcp-refcache) to handle large results efficiently:

1. **Large results are cached** - When a tool returns data that exceeds the preview size, it's stored in the cache
2. **References are returned** - The tool returns a `ref_id` and a preview/sample of the data
3. **Full data on demand** - Use `get_cached_result(ref_id=...)` to retrieve the complete data

This prevents context window bloat when working with large datasets like price histories or Monte Carlo simulations.

## Development

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip

### Setup

```bash
# Clone and install
git clone https://github.com/l4b4r4b4b4/portfolio-mcp
cd portfolio-mcp
uv sync

# Run tests
uv run pytest --cov

# Lint and format
uv run ruff check .
uv run ruff format .
```

### Running Locally

```bash
# stdio mode (for MCP clients)
uv run portfolio-mcp stdio

# SSE mode (for web clients)
uv run portfolio-mcp sse --port 8080

# Streamable HTTP mode
uv run portfolio-mcp streamable-http --port 8080
```

## Configuration

Environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `LOG_LEVEL` | Logging level | `INFO` |
| `CACHE_TTL` | Default cache TTL in seconds | `3600` |

## License

MIT License - see [LICENSE](LICENSE) for details.

## Related Projects

- [mcp-refcache](https://github.com/l4b4r4b4b4/mcp-refcache) - Reference-based caching for MCP servers
- [fastmcp-template](https://github.com/l4b4r4b4b4/fastmcp-template) - Template this project was built from
- [FinQuant](https://github.com/fmilthaler/FinQuant) - Financial portfolio analysis library