Skip to main content
Glama
koyeliaghosh

Modal MCP Stock Analysis Server

by koyeliaghosh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

🚀 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

Related MCP server: Yahoo Finance MCP Server

✨ 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 🚀

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Taiwan Stock Agent

    clsung
    A
    license
    C
    quality
    D
    maintenance
    Provides comprehensive Taiwan stock market data and analysis through MCP tools. Enables querying real-time stock prices, historical data, company information, technical analysis, and market overviews for TWSE and TPEx listed companies.
    8
    16
    MIT

  • Yahoo Finance MCP Server

    danishashko
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides real-time stock market data for Claude Desktop and MCP-compatible clients, enabling natural language queries for quotes, historical prices, company profiles, financial statements, analyst ratings, comparisons, news, options, holdings, dividends, estimates, symbol search, and market status.
    210 npm
    21
    MIT

  • FinAgent

    gmoneyn
    A
    license
    A
    quality
    C
    maintenance
    Provides live stock data and market news for financial analysis via any MCP-compatible AI app.
    2
    MIT