Portfolio

This portfolio MCP server provides a comprehensive suite for managing portfolios, sourcing market data, performing analytics, and optimizing allocations with reference-based caching to keep large results efficient. It enables you to create and compare portfolios, analyze risk and returns, and explore scenario-based optimization against a range of data sources.

How to use

You interact with portfolio-mcp through an MCP client that connects via stdio. Start the local server, then issue natural language prompts to manage portfolios, fetch metrics, run optimizations, and view results. Large results are cached so your prompts stay lightweight while you can retrieve full data on demand using the caching tools.

How to install

Prerequisites you need before installation are Python 3.12+ and a runtime to execute MCP servers (uv is recommended). If you prefer a local Python environment, ensure you have Python and a package manager ready.

# Option 1: Using uv (recommended)

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

# Install dependencies via the MCP runtime
uv sync

# Run the server in stdio mode
uv run portfolio-mcp stdio

# Option 2: Using pip

pip install portfolio-mcp
portfolio-mcp stdio

Configuration and runtime details

To connect with Claude Desktop or other MCP clients, you will run the server in stdio mode and configure the client to invoke it with the appropriate command and arguments.

{
  "mcpServers": {
    "portfolio_mcp": {
      "command": "uv",
      "args": ["run", "portfolio-mcp", "stdio"]
    }
  }
}

Available tools

create_portfolio

Create a new portfolio with symbols and initial weights stored with persistent backing.

get_portfolio

Retrieve portfolio details and computed metrics such as returns and risk metrics.

list_portfolios

List all portfolios stored in the system.

delete_portfolio

Remove a portfolio from storage.

update_portfolio_weights

Update the weights for an existing portfolio.

clone_portfolio

Create a copy of a portfolio, with optional new weights.

get_portfolio_metrics

Compute comprehensive metrics including return, volatility, Sharpe, Sortino, and VaR.

get_returns

Provide daily, daily-log, or cumulative returns for portfolios.

get_correlation_matrix

Analyze correlations between assets within a portfolio.

get_covariance_matrix

Return the variance-covariance matrix for portfolio assets.

get_individual_stock_metrics

Return per-asset statistics such as standalone returns and volatility.

get_drawdown_analysis

Analyze maximum drawdown and recovery dynamics.

compare_portfolios

Provide side-by-side comparisons of multiple portfolios.

optimize_portfolio

Optimize weights for objectives like maximum Sharpe or minimum volatility.

get_efficient_frontier

Generate a set of efficient frontier points for different risk levels.

run_monte_carlo

Perform Monte Carlo simulations to assess portfolio risk and outcomes.

apply_optimization

Apply optimization results to update stored portfolios.

generate_price_series

Create synthetic GBM price series for testing or scenario analysis.

generate_portfolio_scenarios

Create multiple scenario datasets for stress testing.

get_sample_portfolio_data

Provide sample data suitable for testing or demonstrations.

get_trending_coins

Fetch trending cryptocurrencies from CoinGecko.

search_crypto_coins

Search for cryptocurrency assets by name or symbol.

get_crypto_info

Provide detailed information about a cryptocurrency asset.

list_crypto_symbols

List available cryptocurrency symbol mappings.

get_cached_result

Retrieve cached large results by reference ID.