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)}"