portfolio-mcp

Create a new portfolio and store it in RefCache.

Creates a portfolio from real market data, provided data, or synthetic data. The portfolio is stored persistently and can be retrieved, analyzed, and optimized.

Args: name: Unique name for the portfolio (e.g., 'stocks', 'crypto'). symbols: List of asset symbols. - For stocks/ETFs: ['AAPL', 'GOOG', 'MSFT', 'SPY'] - For crypto via Yahoo: ['BTC-USD', 'ETH-USD'] - For crypto via CoinGecko: ['BTC', 'ETH', 'SOL'] weights: Optional allocation weights per symbol. Must sum to 1.0. If None, equal weights are used. prices: Optional price data per symbol as dict of lists. If provided, overrides source parameter. dates: Optional list of date strings (ISO format) for price data. Required if prices is provided. days: Number of trading days for synthetic data (default: 252). risk_free_rate: Risk-free rate for calculations (default: 0.02). seed: Random seed for synthetic data generation. source: Data source for prices (default: "synthetic"): - "synthetic": Generate GBM simulated data - "yahoo": Fetch from Yahoo Finance (stocks, ETFs, crypto) - "crypto": Fetch from CoinGecko API (crypto only) period: Period for market data (default: "1y"). Options: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max

Returns: Dictionary containing: - name: Portfolio name - ref_id: RefCache reference ID for retrieval - symbols: List of symbols in the portfolio - weights: Allocation weights - metrics: Initial portfolio metrics (return, volatility, sharpe) - source: Data source used - created_at: ISO timestamp

Example: ``` # Create portfolio with real stock data result = create_portfolio( name="tech_stocks", symbols=["AAPL", "GOOG", "MSFT"], source="yahoo", period="1y" )

# Create crypto portfolio from CoinGecko
result = create_portfolio(
    name="crypto_portfolio",
    symbols=["BTC", "ETH", "SOL"],
    source="crypto"
)

# Create portfolio with synthetic data (for testing)
result = create_portfolio(
    name="test_portfolio",
    symbols=["A", "B", "C"],
    source="synthetic",
    seed=42
)
```

Get detailed information about a stored portfolio.

Retrieves comprehensive information about a portfolio including its allocation, metrics, and settings.

Args: name: The portfolio name.

Returns: Dictionary containing full portfolio details, or error if not found.

Example: info = get_portfolio(name="tech_stocks") print(f"Sharpe Ratio: {info['metrics']['sharpe_ratio']}")

List all stored portfolios with summary information.

Returns a list of all portfolios in the store with their key metrics and metadata.

Returns: Dictionary containing: - portfolios: List of portfolio summaries - count: Number of portfolios

Example: result = list_portfolios() for pf in result['portfolios']: print(f"{pf['name']}: Sharpe={pf['metrics']['sharpe']:.2f}")

Delete a stored portfolio.

Permanently removes a portfolio from storage.

Args: name: The portfolio name to delete.

Returns: Dictionary with deletion status.

Example: result = delete_portfolio(name="old_portfolio") if result['deleted']: print("Portfolio deleted successfully")

Update the allocation weights of an existing portfolio.

Changes the weight distribution across assets in a portfolio and recalculates all metrics.

Args: name: The portfolio name. weights: New allocation weights per symbol. Must sum to 1.0.

Returns: Updated portfolio information with new metrics.

Example: result = update_portfolio_weights( name="tech_stocks", weights={"GOOG": 0.5, "AMZN": 0.3, "AAPL": 0.2} ) print(f"New Sharpe: {result['metrics']['sharpe_ratio']}")

Clone an existing portfolio, optionally with new weights.

Creates a copy of a portfolio, useful for testing different allocation strategies on the same underlying assets.

Args: source_name: The name of the portfolio to clone. new_name: The name for the cloned portfolio. new_weights: Optional new weights. If None, uses source weights.

Returns: New portfolio information.

Example: ``` # Clone with same weights result = clone_portfolio( source_name="tech_stocks", new_name="tech_stocks_v2" )

# Clone with different weights
result = clone_portfolio(
    source_name="tech_stocks",
    new_name="tech_aggressive",
    new_weights={"GOOG": 0.6, "AMZN": 0.3, "AAPL": 0.1}
)
```

Get comprehensive metrics for a portfolio.

    Calculates and returns all key portfolio metrics including
    risk-adjusted returns, volatility measures, and risk metrics.

    Args:
        name: The portfolio name.

    Returns:
        Dictionary containing:
        - expected_return: Annualized expected return
        - volatility: Annualized volatility (standard deviation)
        - sharpe_ratio: Risk-adjusted return (Sharpe)
        - sortino_ratio: Downside risk-adjusted return (Sortino)
        - value_at_risk: VaR at 95% confidence
        - downside_risk: Target downside deviation
        - skewness: Skewness per stock
        - kurtosis: Kurtosis per stock
        - beta: Portfolio beta (if market index available)
        - treynor_ratio: Treynor ratio (if beta available)

    Example:
        ```
        metrics = get_portfolio_metrics(name="tech_stocks")
        print(f"Expected Return: {metrics['expected_return']:.2%}")
        print(f"Volatility: {metrics['volatility']:.2%}")
        print(f"Sharpe Ratio: {metrics['sharpe_ratio']:.2f}")
        ```
    

Caching Behavior:

• Any input parameter can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get returns data for a portfolio.

    Calculates different types of returns from the portfolio's
    price data.

    Args:
        name: The portfolio name.
        return_type: Type of returns to calculate:
            - "daily": Daily percentage returns
            - "log": Daily log returns
            - "cumulative": Cumulative returns from start
        as_percentage: If True, multiply by 100 for percentage display.

    Returns:
        Dictionary containing:
        - return_type: The type of returns calculated
        - dates: List of date strings
        - returns: Dict of returns per symbol
        - portfolio_returns: Weighted portfolio returns
        - statistics: Summary statistics (mean, std, min, max)

    Example:
        ```
        # Get daily returns
        result = get_returns(name="tech_stocks", return_type="daily")

        # Get cumulative returns for growth chart
        result = get_returns(name="tech_stocks", return_type="cumulative")
        ```
    

Caching Behavior:

• Any input parameter can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get the correlation matrix for portfolio assets.

    Calculates pairwise correlations between all assets in the
    portfolio based on daily returns.

    Args:
        name: The portfolio name.

    Returns:
        Dictionary containing:
        - symbols: List of symbols
        - correlation_matrix: 2D correlation matrix
        - correlations: Readable format with symbol pairs

    Example:
        ```
        result = get_correlation_matrix(name="tech_stocks")
        # Check correlation between GOOG and AMZN
        corr = result['correlations']['GOOG']['AMZN']
        ```
    

Caching Behavior:

• Any input parameter can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Get the covariance matrix for portfolio assets.

    Calculates pairwise covariances between all assets in the
    portfolio based on daily returns.

    Args:
        name: The portfolio name.
        annualized: If True, annualize the covariance (multiply by 252).

    Returns:
        Dictionary containing:
        - symbols: List of symbols
        - covariance_matrix: 2D covariance matrix
        - variances: Individual asset variances (diagonal)

    Example:
        ```
        result = get_covariance_matrix(name="tech_stocks")
        print(f"GOOG variance: {result['variances']['GOOG']}")
        ```
    

Caching Behavior:

• Any input parameter can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Compare multiple portfolios side by side.

Retrieves metrics for multiple portfolios and ranks them by key performance indicators.

Args: names: List of portfolio names to compare.

Returns: Dictionary containing: - portfolios: Dict of metrics per portfolio - rankings: Rankings by each metric - best_by_metric: Best portfolio for each metric

Example: result = compare_portfolios( names=["stocks", "crypto", "metals"] ) print(f"Best Sharpe: {result['best_by_metric']['sharpe_ratio']}")

Get metrics for each individual stock in a portfolio.

    Calculates return and volatility metrics for each stock
    separately, useful for identifying best/worst performers.

    Args:
        name: The portfolio name.

    Returns:
        Dictionary containing metrics per stock:
        - mean_return: Average daily return (annualized)
        - volatility: Standard deviation (annualized)
        - sharpe_ratio: Individual Sharpe ratio
        - weight: Current allocation weight

    Example:
        ```
        result = get_individual_stock_metrics(name="tech_stocks")
        for symbol, metrics in result['stocks'].items():
            print(f"{symbol}: Return={metrics['mean_return']:.2%}")
        ```
    

Caching Behavior:

• Any input parameter can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Analyze portfolio drawdowns.

    Calculates maximum drawdown and drawdown periods for the
    portfolio, useful for risk assessment.

    Args:
        name: The portfolio name.

    Returns:
        Dictionary containing:
        - max_drawdown: Maximum drawdown percentage
        - max_drawdown_period: Start and end dates of max drawdown
        - current_drawdown: Current drawdown from peak
        - recovery_needed: Percentage gain needed to recover

    Example:
        ```
        result = get_drawdown_analysis(name="tech_stocks")
        print(f"Max Drawdown: {result['max_drawdown']:.2%}")
        ```
    

Caching Behavior:

• Any input parameter can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Optimize portfolio weights using Efficient Frontier.

    Finds optimal portfolio weights based on the specified optimization
    method. Uses numerical optimization (scipy) to find the solution.

    Args:
        name: The portfolio name.
        method: Optimization method:
            - "max_sharpe": Maximize Sharpe ratio (default)
            - "min_volatility": Minimize portfolio volatility
            - "efficient_return": Minimize volatility for target return
            - "efficient_volatility": Maximize return for target volatility
        target_return: Required for "efficient_return" method.
            The target annualized return to achieve.
        target_volatility: Required for "efficient_volatility" method.
            The target annualized volatility.

    Returns:
        Dictionary containing:
        - method: Optimization method used
        - optimal_weights: Dict of optimal weights per symbol
        - expected_return: Expected return of optimal portfolio
        - volatility: Volatility of optimal portfolio
        - sharpe_ratio: Sharpe ratio of optimal portfolio
        - original: Original portfolio metrics for comparison
        - improvement: Improvement over original portfolio

    Example:
        ```
        # Maximize Sharpe ratio
        result = optimize_portfolio(name="tech_stocks", method="max_sharpe")

        # Minimize volatility
        result = optimize_portfolio(name="tech_stocks", method="min_volatility")

        # Target 15% return with minimum volatility
        result = optimize_portfolio(
            name="tech_stocks",
            method="efficient_return",
            target_return=0.15
        )
        ```
    

Caching Behavior:

• Any input parameter can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Run Monte Carlo simulation to find optimal portfolios.

Generates random portfolio weight combinations and evaluates their risk/return characteristics to find optimal allocations.

Note: This is computationally intensive. For large num_trials, consider using the Efficient Frontier method instead which provides mathematically optimal solutions.

Args: name: The portfolio name. num_trials: Number of random portfolios to generate (default: 5000).

Returns: Dictionary containing: - num_trials: Number of simulations run - min_volatility_portfolio: Portfolio with minimum volatility - max_sharpe_portfolio: Portfolio with maximum Sharpe ratio - simulation_stats: Statistics about the simulation - sample_portfolios: Sample of generated portfolios

Example: result = run_monte_carlo(name="tech_stocks", num_trials=10000) best = result['max_sharpe_portfolio'] print(f"Best Sharpe: {best['sharpe_ratio']:.2f}") print(f"Optimal weights: {best['weights']}")

Generate efficient frontier data points for visualization.

    Calculates points along the efficient frontier, which represents
    the set of optimal portfolios offering the highest expected return
    for a given level of risk.

    Args:
        name: The portfolio name.
        num_points: Number of points to generate along the frontier.

    Returns:
        Dictionary containing:
        - frontier_points: List of {volatility, expected_return} points
        - optimal_sharpe: Maximum Sharpe ratio portfolio
        - optimal_min_volatility: Minimum volatility portfolio
        - individual_stocks: Individual stock positions
        - current_portfolio: Current portfolio position

    Example:
        ```
        result = get_efficient_frontier(name="tech_stocks", num_points=100)

        # Plot the frontier
        for point in result['frontier_points']:
            print(f"Vol: {point['volatility']:.2%}, Return: {point['expected_return']:.2%}")
        ```
    

Caching Behavior:

• Any input parameter can accept a ref_id from a previous tool call

• Large results return ref_id + preview; use get_cached_result to paginate

• All responses include ref_id for future reference

Preview Size: server default. Override per-call with get_cached_result(ref_id, max_size=...).

Apply optimization and update portfolio weights.

Optimizes the portfolio using the specified method and updates the stored portfolio with the new optimal weights.

Args: name: The portfolio name. method: Optimization method (same as optimize_portfolio). target_return: Target return for "efficient_return" method. target_volatility: Target volatility for "efficient_volatility" method.

Returns: Updated portfolio information with new weights and metrics.

Example: result = apply_optimization(name="tech_stocks", method="max_sharpe") print(f"New Sharpe: {result['new_metrics']['sharpe_ratio']:.2f}")

Generate synthetic price series using Geometric Brownian Motion.

Creates realistic-looking stock price data with customizable parameters for each asset. Supports correlated assets via a correlation matrix.

Large results are cached and returned as a reference with preview. Use get_cached_result to paginate through the full price series.

Args: symbols: List of asset symbols (e.g., ['GOOG', 'AMZN', 'AAPL']). days: Number of trading days to generate (default: 252, one year). initial_prices: Optional initial price per symbol. Defaults to 100.0 for all symbols. annual_returns: Optional expected annual return per symbol. Defaults to 0.08 (8%) for all symbols. annual_volatilities: Optional annual volatility per symbol. Defaults to 0.20 (20%) for all symbols. correlation_matrix: Optional correlation matrix for the assets. Should be a symmetric positive semi-definite matrix. Defaults to identity matrix (uncorrelated). seed: Random seed for reproducibility.

Returns: Dictionary containing: - ref_id: Reference ID for accessing full cached data - symbols: List of symbols - preview: Sample of the price data - total_items: Total number of data points (days) - parameters: Generation parameters used - message: Instructions for pagination

Example: ``` # Generate 1 year of data for 3 tech stocks result = generate_price_series( symbols=["GOOG", "AMZN", "AAPL"], days=252, annual_returns={"GOOG": 0.12, "AMZN": 0.15, "AAPL": 0.10}, annual_volatilities={"GOOG": 0.25, "AMZN": 0.30, "AAPL": 0.22}, seed=42 )

# Use ref_id to paginate
page2 = get_cached_result(ref_id=result["ref_id"], page=2)
```

Generate multiple portfolio scenarios with varying parameters.

Useful for testing optimization strategies across different market conditions.

Large results are cached and returned as a reference with preview. Use get_cached_result to paginate through the full scenario data.

Args: base_symbols: List of asset symbols for all scenarios. num_scenarios: Number of different scenarios to generate. days: Number of trading days per scenario. return_range: (min, max) annual return range for random generation. volatility_range: (min, max) annual volatility range. seed: Random seed for reproducibility.

Returns: Dictionary containing: - ref_id: Reference ID for accessing full cached data - num_scenarios: Number of scenarios generated - preview: Sample of scenarios - summary: Summary statistics across scenarios

Get pre-defined sample portfolio data for quick testing.

Returns sample data for a diversified portfolio with realistic parameters based on historical market behavior.

Returns: Dictionary with sample portfolio data ready for use with create_portfolio().

Get trending cryptocurrencies from CoinGecko.

Returns a list of coins that are trending in the last 24 hours, useful for discovering popular assets to analyze.

Returns: Dictionary containing: - coins: List of trending coin info (id, name, symbol, rank) - fetched_at: ISO timestamp

Example: result = get_trending_coins() for coin in result['coins']: print(f"{coin['name']} ({coin['symbol']})")

Search for cryptocurrencies on CoinGecko.

Find coins by name, symbol, or keyword. Useful for discovering coin IDs to use with create_portfolio.

Args: query: Search query (e.g., 'bitcoin', 'defi', 'layer 2').

Returns: Dictionary containing: - coins: List of matching coins (id, name, symbol, market_cap_rank) - count: Number of results - fetched_at: ISO timestamp

Example: # Search for DeFi coins result = search_crypto_coins(query="defi") for coin in result['coins']: print(f"{coin['name']} ({coin['symbol']}) - Rank: {coin['market_cap_rank']}")

Get detailed information about a cryptocurrency.

Retrieves current price, market cap, volume, and 24h changes.

Args: symbol: Crypto symbol (e.g., 'BTC', 'ETH', 'SOL') or CoinGecko ID.

Returns: Dictionary containing coin information: - id, name, symbol - current_price, market_cap, total_volume - high_24h, low_24h, price_change_24h - market_cap_rank, categories

Example: result = get_crypto_info(symbol="BTC") print(f"Bitcoin: ${result['current_price']:,.2f}") print(f"24h change: {result['price_change_percentage_24h']:.2f}%")

List supported cryptocurrency symbols and their CoinGecko IDs.

Returns the mapping of common crypto symbols (like BTC, ETH) to their CoinGecko API identifiers.

Returns: Dictionary containing: - symbols: Dict mapping symbol to CoinGecko ID - count: Number of supported symbols - usage: How to use with create_portfolio

Example: result = list_crypto_symbols() print(f"Supported: {list(result['symbols'].keys())[:10]}...")

Retrieve a cached result, optionally with pagination.

Use this to:

• Get a preview of a cached value

• Paginate through large sequences, price series, or returns data

• Access specific pages of a cached result

Args: ref_id: The reference ID returned by tools (e.g., from generate_price_series). page: Page number (1-indexed). If not provided, returns the default preview. page_size: Items per page. Default varies by data type (typically 50).

Returns: Dictionary containing: - ref_id: The reference ID - preview: The data for the current page/preview - preview_strategy: How the preview was generated (sample, truncate, paginate) - total_items: Total number of items in the full dataset - page: Current page number (if paginated) - total_pages: Total pages available (if paginated)

Example: ``` # Generate large price series (returns ref_id + preview) result = generate_price_series(symbols=["AAPL", "GOOG"], days=500)

# Get page 2 of the cached data
page2 = get_cached_result(ref_id=result["ref_id"], page=2, page_size=50)

# Get page 5
page5 = get_cached_result(ref_id=result["ref_id"], page=5)
```

Check server health status.

Returns server health information including cache status and number of stored portfolios.

Returns: Health status information.