Schema | portfolio-mcp

Server Configuration

Describes the environment variables required to run the server.

Name	Required	Description	Default
`CACHE_TTL`	No	Default cache TTL in seconds	3600
`LOG_LEVEL`	No	Logging level	INFO

Capabilities

Features and capabilities supported by this server

Capability	Details
`tools`	{ "listChanged": true }
`prompts`	{ "listChanged": false }
`resources`	{ "subscribe": false, "listChanged": false }
`experimental`	{ "tasks": { "list": {}, "cancel": {}, "requests": { "tools": { "call": {} }, "prompts": { "get": {} }, "resources": { "read": {} } } } }

Tools

Functions exposed to the LLM to take actions

Name	Description
create_portfolio	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_portfolio	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_portfolios	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_portfolio	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_portfolio_weights	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_portfolio	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_portfolio_metrics	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	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_correlation_matrix	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_covariance_matrix	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_portfolios	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_individual_stock_metrics	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=...)`.
get_drawdown_analysis	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	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	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']}")`
get_efficient_frontier	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	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_price_series	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_portfolio_scenarios	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_sample_portfolio_data	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_coins	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_crypto_coins	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_crypto_info	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_crypto_symbols	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]}...")`
get_cached_result	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) ```
health_check	Check server health status. Returns server health information including cache status and number of stored portfolios. Returns: Health status information.

Prompts

Interactive templates invoked by user choice

Name	Description
No prompts

Resources

Contextual data attached and managed by the client

Name	Description
No resources

portfolio-mcp

Server Configuration

Capabilities

Tools

Prompts

Resources

Latest Blog Posts

MCP directory API