modal-mcp-server

koyeliaghosh/modal-mcp-server

3.2

If you are the rightful owner of modal-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

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

Tools
3
Resources
0
Prompts
0

šŸš€ Modal MCP 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

Built for the Hugging Face Gradio MCP Hackathon šŸš€