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)

Using pip

Quick Start

Connect to Claude Desktop

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

Basic Usage

Once connected, you can use natural language to:

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

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

Running Locally

Configuration

Environment variables:

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