Modal Stock Analysis Server

A cloud-hosted Model Context Protocol (MCP) server for real-time stock analysis, built with Modal and FastAPI.

📋 Overview

This MCP server provides stock analysis tools through a RESTful API, demonstrating how to implement the Model Context Protocol in a distributed, cloud-native architecture.

🏗️ Architecture

• Backend: Modal serverless platform
• Framework: FastAPI for HTTP endpoints
• Protocol: Model Context Protocol (MCP) implementation
• Data Source: yfinance for real-time stock market data

✨ Features

🔧 MCP Tools Available:

1. get_stock_price - Retrieve current stock price and basic company information
2. analyze_stock_comprehensive - Complete investment analysis with scoring algorithm
3. smart_ticker_search - Convert company names to ticker symbols

📊 Analysis Capabilities:

• Real-time stock price lookup
• YTD return calculations
• P/E ratio analysis
• Investment scoring (0-100 scale)
• Buy/Hold/Sell recommendations
• Smart company name → ticker conversion

🚀 Quick Start

Prerequisites

• Python 3.11+
• Modal account (modal.com)
• Modal CLI installed

Installation & Setup

1. Clone the repository

   git clone <your-repo-url>
   cd modal-mcp-server
   

2. Install Modal CLI

   pip install modal
   

3. Authenticate with Modal

   modal token new
   

4. Deploy the MCP server

   modal deploy modal_mcp_complete.py
   

📡 API Endpoints

Base URL

https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run

Available Endpoints:

GET / - Server Information

curl https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/

GET /health - Health Check

curl https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/health

GET /tools - MCP Tools Discovery

curl https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/tools

POST /call - Execute MCP Tool

curl -X POST https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/call \
  -H "Content-Type: application/json" \
  -d '{"name": "TOOL_NAME", "arguments": {"key": "value"}}'

🛠️ Usage Examples

Stock Price Lookup

curl -X POST https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_stock_price", "arguments": {"symbol": "AAPL"}}'

Response:

{
  "success": true,
  "tool": "get_stock_price",
  "result": [{
    "symbol": "TSLA",
    "company_name": "Tesla, Inc.",
    "current_price": 248.50,
    "market_cap": 790000000000,
    "sector": "Consumer Cyclical"
  }],
  "timestamp": "2025-06-10T..."
}

Comprehensive Analysis

curl -X POST https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/call \
  -H "Content-Type: application/json" \
  -d '{"name": "analyze_stock_comprehensive", "arguments": {"symbol": "AAPL"}
  }'

Response:

{
  "success": true,
  "tool": "analyze_stock_comprehensive",
  "result": [{
    "symbol": "AAPL",
    "company_name": "Apple Inc.",
    "current_price": 185.50,
    "ytd_return": 12.5,
    "pe_ratio": 28.5,
    "investment_score": 75,
    "recommendation": "Buy",
    "sector": "Technology"
  }],
  "timestamp": "2025-06-10T..."
}

Smart Ticker Search

curl -X POST https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "smart_ticker_search",
    "arguments": {"query": "microsoft"}
  }'

🔧 Configuration

Environment Variables

• MCP_SERVER_SECRET - Optional server secret for authentication

Modal Secrets

The server can optionally use Modal secrets for configuration:

stock_secrets = modal.Secret.from_name("Stock-api-config")

📁 Project Structure

modal-mcp-server/
├── modal_mcp_complete.py     # Main MCP server implementation
├── README.md                 # This file
└── requirements.txt          # Dependencies (handled by Modal)

🧠 Investment Scoring Algorithm

The comprehensive analysis uses a proprietary scoring algorithm:

score = 50  # Base score
if ytd_return > 15: score += 25
elif ytd_return > 5: score += 15
elif ytd_return > 0: score += 5

if 10 < pe_ratio < 25: score += 15

# Final score: 0-100
recommendation = "Buy" if score >= 70 else "Hold" if score >= 50 else "Sell"

🎯 Supported Stock Symbols

Direct Ticker Symbols:

• Tech: AAPL, GOOGL, MSFT, TSLA, META, NVDA, AMD, INTC
• Finance: JPM, BAC, WFC, GS
• Consumer: WMT, KO, PEP, NKE, MCD
• ETFs: SPY, QQQ

Company Name Mapping:

• apple → AAPL
• microsoft → MSFT
• google/alphabet → GOOGL
• amazon → AMZN
• tesla → TSLA
• meta/facebook → META
• netflix → NFLX
• nvidia → NVDA

🚀 Development

Local Testing

# Test health endpoint
curl http://localhost:8000/health

# Test tools discovery
curl http://localhost:8000/tools

# Test tool execution
curl -X POST http://localhost:8000/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_stock_price", "arguments": {"symbol": "AAPL"}}'

Deployment

# Deploy to Modal
modal deploy modal_mcp_complete.py

# Check deployment status
modal app list

# View logs
modal logs <app-id>

🔍 Monitoring & Debugging

Health Checks

Monitor server health via the /health endpoint:

curl https://koyeliaghoshroy1--mcp-stock-analysis-server-web-app.modal.run/health

Error Handling

The server provides detailed error responses:

{
  "error": "No data available for INVALID",
  "success": false,
  "timestamp": "2025-06-10T..."
}

📚 MCP Protocol Implementation

This server implements the Model Context Protocol specification:

• Tool Discovery: GET /tools returns available MCP tools
• Tool Execution: POST /call executes tools with proper request/response format
• Error Handling: Standardized error responses
• Type Safety: JSON schema validation for tool inputs

🤝 Integration Examples

Python Client

import requests

def call_mcp_tool(tool_name, arguments):
    response = requests.post(
        "https://your-modal-url/call",
        json={"name": tool_name, "arguments": arguments}
    )
    return response.json()

# Get stock price
result = call_mcp_tool("get_stock_price", {"symbol": "AAPL"})

JavaScript Client

async function callMCPTool(toolName, arguments) {
  const response = await fetch('https://your-modal-url/call', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: toolName, arguments })
  });
  return response.json();
}

// Analyze stock
const analysis = await callMCPTool('analyze_stock_comprehensive', { symbol: 'TSLA' });

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Modal - For serverless cloud infrastructure
• Hugging Face - For hackathon organization
• yfinance - For stock market data
• FastAPI - For web framework
• MCP Community - For protocol specification

🔗 Related Links

• Frontend Interface: [Gradio MCP Client] (https://huggingface.co/spaces/Agents-MCP-Hackathon/mcp-stock-analysis-hackathon)
• Modal Platform: modal.com
• MCP Specification: Model Context Protocol

---

Built for the Hugging Face Gradio MCP Hackathon 🚀