AlphaVantage-MCP

Instructions

Implementation Reference

• src/alpha_vantage_mcp/server.py:637-660 (handler)

  Executes the get-historical-earnings tool: fetches EARNINGS data from Alpha Vantage API using make_alpha_request and formats the response using format_historical_earnings.
  elif name == "get-historical-earnings": symbol = arguments.get("symbol") limit_annual = arguments.get("limit_annual", 5) limit_quarterly = arguments.get("limit_quarterly", 8) if not symbol: return [types.TextContent(type="text", text="Missing symbol parameter")] symbol = symbol.upper() async with httpx.AsyncClient() as client: earnings_data = await make_alpha_request( client, "EARNINGS", symbol ) if isinstance(earnings_data, str): return [types.TextContent(type="text", text=f"Error: {earnings_data}")] formatted_earnings = format_historical_earnings(earnings_data, limit_annual, limit_quarterly) earnings_text = f"Historical earnings for {symbol}:\n\n{formatted_earnings}" return [types.TextContent(type="text", text=earnings_text)]
• src/alpha_vantage_mcp/server.py:292-317 (schema)

  Defines the input schema and parameters for the get-historical-earnings tool.
  types.Tool( name="get-historical-earnings", description="Get historical earnings data for a specific company", inputSchema={ "type": "object", "properties": { "symbol": { "type": "string", "description": "Stock symbol for the company (e.g., AAPL, MSFT, IBM)" }, "limit_annual": { "type": "integer", "description": "Optional: Number of annual earnings to return (default: 5)", "default": 5, "minimum": 1 }, "limit_quarterly": { "type": "integer", "description": "Optional: Number of quarterly earnings to return (default: 8)", "default": 8, "minimum": 1 } }, "required": ["symbol"], }, ),
• src/alpha_vantage_mcp/server.py:292-317 (registration)

  Registers the get-historical-earnings tool in the MCP server list_tools() handler.
  types.Tool( name="get-historical-earnings", description="Get historical earnings data for a specific company", inputSchema={ "type": "object", "properties": { "symbol": { "type": "string", "description": "Stock symbol for the company (e.g., AAPL, MSFT, IBM)" }, "limit_annual": { "type": "integer", "description": "Optional: Number of annual earnings to return (default: 5)", "default": 5, "minimum": 1 }, "limit_quarterly": { "type": "integer", "description": "Optional: Number of quarterly earnings to return (default: 8)", "default": 8, "minimum": 1 } }, "required": ["symbol"], }, ),
• src/alpha_vantage_mcp/tools.py:423-504 (helper)

  Formats the raw earnings data from Alpha Vantage EARNINGS API into a readable text output, handling both annual and quarterly earnings with limits.
  def format_historical_earnings(earnings_data: Dict[str, Any], limit_annual: int = 5, limit_quarterly: int = 8) -> str: """Format historical earnings data into a concise string. Args: earnings_data: The response data from the Alpha Vantage EARNINGS endpoint limit_annual: Number of annual earnings to display (default: 5) limit_quarterly: Number of quarterly earnings to display (default: 8) Returns: A formatted string containing the historical earnings information """ try: if "Error Message" in earnings_data: return f"Error: {earnings_data['Error Message']}" symbol = earnings_data.get("symbol", "Unknown") formatted = [f"Historical Earnings for {symbol}:\n\n"] # Format Annual Earnings annual_earnings = earnings_data.get("annualEarnings", []) if annual_earnings: formatted.append("=== ANNUAL EARNINGS ===\n") display_annual = annual_earnings[:limit_annual] if limit_annual > 0 else annual_earnings for earning in display_annual: fiscal_date = earning.get("fiscalDateEnding", "N/A") reported_eps = earning.get("reportedEPS", "N/A") formatted.append(f"Fiscal Year End: {fiscal_date}\n") formatted.append(f"Reported EPS: ${reported_eps}\n") formatted.append("---\n") if limit_annual > 0 and len(annual_earnings) > limit_annual: formatted.append(f"... and {len(annual_earnings) - limit_annual} more annual reports\n") formatted.append("\n") # Format Quarterly Earnings quarterly_earnings = earnings_data.get("quarterlyEarnings", []) if quarterly_earnings: formatted.append("=== QUARTERLY EARNINGS ===\n") display_quarterly = quarterly_earnings[:limit_quarterly] if limit_quarterly > 0 else quarterly_earnings for earning in display_quarterly: fiscal_date = earning.get("fiscalDateEnding", "N/A") reported_date = earning.get("reportedDate", "N/A") reported_eps = earning.get("reportedEPS", "N/A") estimated_eps = earning.get("estimatedEPS", "N/A") surprise = earning.get("surprise", "N/A") surprise_pct = earning.get("surprisePercentage", "N/A") report_time = earning.get("reportTime", "N/A") formatted.append(f"Fiscal Quarter End: {fiscal_date}\n") formatted.append(f"Reported Date: {reported_date}\n") formatted.append(f"Reported EPS: ${reported_eps}\n") formatted.append(f"Estimated EPS: ${estimated_eps}\n") # Format surprise with proper handling if surprise != "N/A" and surprise_pct != "N/A": try: surprise_float = float(surprise) surprise_pct_float = float(surprise_pct) if surprise_float >= 0: formatted.append(f"Surprise: +${surprise_float:.2f} (+{surprise_pct_float:.2f}%)\n") else: formatted.append(f"Surprise: ${surprise_float:.2f} ({surprise_pct_float:.2f}%)\n") except ValueError: formatted.append(f"Surprise: {surprise} ({surprise_pct}%)\n") else: formatted.append(f"Surprise: {surprise} ({surprise_pct}%)\n") formatted.append(f"Report Time: {report_time}\n") formatted.append("---\n") if limit_quarterly > 0 and len(quarterly_earnings) > limit_quarterly: formatted.append(f"... and {len(quarterly_earnings) - limit_quarterly} more quarterly reports\n") if not annual_earnings and not quarterly_earnings: formatted.append("No historical earnings data available\n") return "".join(formatted) except Exception as e: return f"Error formatting historical earnings data: {str(e)}"