AlphaVantage-MCP

Instructions

Implementation Reference

• src/alpha_vantage_mcp/server.py:446-475 (handler)

  The main handler logic for executing the 'get-time-series' tool. Extracts parameters, determines outputsize, fetches data from Alpha Vantage TIME_SERIES_DAILY endpoint, formats using format_time_series helper, and returns formatted text content.
  elif name == "get-time-series": symbol = arguments.get("symbol") if not symbol: return [types.TextContent(type="text", text="Missing symbol parameter")] symbol = symbol.upper() start_date = arguments.get("start_date") end_date = arguments.get("end_date") limit = arguments.get("limit", 5) # Auto-select outputsize: use 'full' when date filtering is requested outputsize = arguments.get("outputsize") if not outputsize: outputsize = "full" if (start_date or end_date) else "compact" async with httpx.AsyncClient() as client: time_series_data = await make_alpha_request( client, "TIME_SERIES_DAILY", symbol, {"outputsize": outputsize} ) if isinstance(time_series_data, str): return [types.TextContent(type="text", text=f"Error: {time_series_data}")] formatted_series = format_time_series(time_series_data, start_date, end_date, limit) series_text = f"Time series data for {symbol}:\n\n{formatted_series}" return [types.TextContent(type="text", text=series_text)]
• src/alpha_vantage_mcp/server.py:86-121 (registration)

  Tool registration in the list_tools handler, defining the name, description, and JSON schema for input validation including symbol, outputsize, date filters, and limit.
  types.Tool( name="get-time-series", description="Get daily time series data for a stock with optional date filtering", inputSchema={ "type": "object", "properties": { "symbol": { "type": "string", "description": "Stock symbol (e.g., AAPL, MSFT)", }, "outputsize": { "type": "string", "description": "compact (latest 100 data points) or full (up to 20 years of data). When start_date or end_date is specified, defaults to 'full'", "enum": ["compact", "full"], "default": "compact" }, "start_date": { "type": "string", "description": "Optional: Start date in YYYY-MM-DD format for filtering results", "pattern": "^20[0-9]{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$" }, "end_date": { "type": "string", "description": "Optional: End date in YYYY-MM-DD format for filtering results", "pattern": "^20[0-9]{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$" }, "limit": { "type": "integer", "description": "Optional: Number of data points to return when no date filtering is applied (default: 5)", "default": 5, "minimum": 1 } }, "required": ["symbol"], }, ),
• src/alpha_vantage_mcp/tools.py:174-263 (helper)

  Supporting helper function that processes and formats the raw time series API response, applying date range filtering, limiting results, and generating a readable text output.
  def format_time_series(time_series_data: Dict[str, Any], start_date: Optional[str] = None, end_date: Optional[str] = None, limit: int = 5) -> str: """Format time series data into a concise string with optional date filtering. Args: time_series_data: The response data from the Alpha Vantage TIME_SERIES_DAILY endpoint start_date: Optional start date in YYYY-MM-DD format for filtering end_date: Optional end date in YYYY-MM-DD format for filtering limit: Number of data points to return when no date filtering is applied Returns: A formatted string containing the time series information """ try: # Get the daily time series data time_series = time_series_data.get("Time Series (Daily)", {}) if not time_series: return "No time series data available in the response" # Get metadata metadata = time_series_data.get("Meta Data", {}) symbol = metadata.get("2. Symbol", "Unknown") last_refreshed = metadata.get("3. Last Refreshed", "Unknown") # Filter by date range if specified filtered_data = {} if start_date or end_date: for date_str, values in time_series.items(): try: date_obj = datetime.strptime(date_str, "%Y-%m-%d") # Check start date filter if start_date: start_obj = datetime.strptime(start_date, "%Y-%m-%d") if date_obj < start_obj: continue # Check end date filter if end_date: end_obj = datetime.strptime(end_date, "%Y-%m-%d") if date_obj > end_obj: continue filtered_data[date_str] = values except ValueError: # Skip invalid date formats continue # Sort filtered data by date (most recent first) sorted_items = sorted(filtered_data.items(), key=lambda x: x[0], reverse=True) else: # Use original data with limit sorted_items = list(time_series.items())[:limit] if not sorted_items: return f"No time series data found for the specified date range" # Build header formatted_data = [ f"Time Series Data for {symbol} (Last Refreshed: {last_refreshed})\n" ] # Add date range info if filtering was applied if start_date or end_date: date_range = "" if start_date and end_date: date_range = f"Date Range: {start_date} to {end_date}" elif start_date: date_range = f"From: {start_date}" elif end_date: date_range = f"Until: {end_date}" formatted_data.append(f"{date_range} ({len(sorted_items)} data points)\n\n") else: formatted_data.append(f"(Showing {len(sorted_items)} most recent data points)\n\n") # Format the data points for date, values in sorted_items: formatted_data.append( f"Date: {date}\n" f"Open: ${values.get('1. open', 'N/A')}\n" f"High: ${values.get('2. high', 'N/A')}\n" f"Low: ${values.get('3. low', 'N/A')}\n" f"Close: ${values.get('4. close', 'N/A')}\n" f"Volume: {values.get('5. volume', 'N/A')}\n" "---\n" ) return "\n".join(formatted_data) except Exception as e: return f"Error formatting time series data: {str(e)}"