portfolio-mcp

A portfolio analysis MCP server powered by mcp-refcache for building AI agent tools that handle financial data efficiently.

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)

# 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

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):

{
  "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 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 (recommended) or pip

Setup

# 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

# 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 for details.

Related Projects

• mcp-refcache - Reference-based caching for MCP servers
• fastmcp-template - Template this project was built from
• FinQuant - Financial portfolio analysis library