StocksMCP

An AI-powered stock research platform built using the Model Context Protocol (MCP). It implements a fully compliant FastMCP server exposing fundamental analysis, local file-based database CRUD tools, and a dynamic dashboard layout via the Prefab UI protocol, combined with a standalone FastAPI + HTML5 interactive browser terminal.

🌐 Live Demo: stocksmcp-dashboard-sg.onrender.com — try it now, no install required (free-tier instance, may take ~30s to wake up on first load).

---

🏗️ Architecture

                       User Prompt (e.g., "Analyze National Aluminium")
                                     │
                                     ▼
                              ┌──────────────┐
                              │  MCP Client  │
                              │   (Agent)    │
                              └──────┬───────┘
                                     │ (stdio connection)
                                     ▼
                              ┌──────────────┐
                              │  MCP Server  │
                              │  (FastMCP)   │
                              └──────┬───────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         ▼                           ▼                           ▼
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  Internet Tool  │         │    CRUD Tool    │         │     UI Tool     │
│                 │         │                 │         │   (Prefab UI)   │
│  yfinance API   │         │  local reports/ │         │  Generative App │
└─────────────────┘         └─────────────────┘         └─────────────────┘

The system is split into two access interfaces:

1. MCP Protocol Interface: For AI agent clients (like Claude Desktop) using Stdio transport and Prefab UI.
2. Standalone Web Terminal: A browser interface at http://localhost:8000 presenting a fully responsive dark-themed terminal with real-time Plotly.js charts, quarterly indicators, and side-by-side stock comparisons.

---

⚡ Key Features

• Internet Data Tool: Real-time fundamentals, quarterly statement retrieval, and historical OHLCV pricing via yfinance.
• Local CRUD Tool: Persistent JSON storage for analyzed stocks under reports/.
• UI Communication (Prefab UI): Exposes structural layout component trees (show_dashboard) to MCP-compatible rendering clients.
• Valuation Estimation Model: Calculates growth-adjusted fair PE, EPS, and valuation gap percentage.
• Growth Scoring System: Evaluates companies out of 10 points based on quarterly revenue/PAT trends, ROE, debt-to-equity, and promoter holdings.
• Interactive Candlestick Charts: Fully interactive Plotly.js charting (Zoom, Pan, Hover details, Date range slider).
• Stock Comparison: Compare two stocks side-by-side on all fundamental metrics.

---

🛠️ Setup Instructions

1. Prerequisites

• Python 3.8 or higher installed on your system.

2. Project Directory Installation

Clone or navigate to the project directory:

cd /Users/pawanthanay/Project/StocksMCP

3. Create a Virtual Environment and Install Dependencies

Initialize a Python virtual environment, activate it, and install all required modules (this also installs prefab-ui, the rendering engine behind the show_dashboard Prefab UI tool):

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

macOS / Homebrew Python troubleshooting: If pip install fails with ImportError: ... Symbol not found: _XML_SetAllocTrackerActivationThreshold (a known Homebrew Python 3.12 ↔ system libexpat mismatch), prefix your pip/python3 commands with the Homebrew expat lib path, e.g.:

export DYLD_LIBRARY_PATH="$(brew --prefix expat)/lib:$DYLD_LIBRARY_PATH"
pip install -r requirements.txt

4. Configuration

Create a .env file from the example:

cp .env.example .env

---

🚀 Running the Application

Option A: Running the Standalone Web Dashboard (Recommended)

This starts the FastAPI web server. You can view the dashboard in any standard browser:

python3 -m src.web_dashboard

Once started, open your browser and go to: 👉 http://localhost:8000

Select stocks from the dropdown (e.g. National Aluminium, TCS, Infosys) to perform live analysis, view interactive Plotly candlestick charts, read AI-generated summaries, and run comparisons.

Option B: Running the MCP Client Agent (Automatic Workflow)

Run the client script to execute the agentic loop. The agent connects to the server, fetches data, performs calculations, saves the JSON report, and registers the Prefab dashboard:

python3 -m src.client "Analyze National Aluminium stock"

To run a different stock, pass it in the prompt:

python3 -m src.client "Analyze TCS stock"

Option C: Testing the MCP Server Directly

To run the server in stdio mode (for Claude Desktop or testing):

python3 -m src.server

---

☁️ Deploying the Web Dashboard (Render)

The web dashboard is a standard FastAPI app and can be deployed for free on Render:

1. Fork or push this repo to your own GitHub account.
2. On Render, choose New + → Blueprint and point it at your repo — it will pick up render.yaml automatically and configure the build (pip install -r requirements.txt) and start (uvicorn src.web_dashboard:app --host 0.0.0.0 --port $PORT) commands.
3. Click Apply / Create Web Service. Render builds and deploys automatically, and redeploys on every push to main.
4. Once live, share the https://<your-service>.onrender.com URL — every visitor gets the same live Yahoo Finance data, fetched fresh per request.

Note on region: pick a region other than US-Oregon if you can — some free-tier shared IP pools (e.g. Render's Oregon pool) are currently IP-blocked by Yahoo Finance, which causes the live dashboard to return empty data even though everything works locally. Singapore's pool is currently unaffected — that's what powers the live demo above.

No server-side secrets are required: each visitor supplies their own optional Gemini API key directly in the dashboard UI (used only for that request, never stored server-side — see gemini_client.py).

Note: Render's free tier spins the service down after periods of inactivity, so the first request after idling can take ~30–60 seconds to wake up.

---

📊 Growth Scoring System

Ratios are checked and scored out of 10 points:

• Revenue Growth QoQ: Growing = 2 points, Flat = 1 point, Declining = 0 points
• PAT Growth QoQ: Growing = 2 points, Flat = 1 point, Declining = 0 points
• ROE (Return on Equity): >15% = 2 points, 10-15% = 1 point, <10% = 0 points
• Debt-to-Equity: <50% (0.5) = 2 points, 50-100% (0.5-1.0) = 1 point, >100% = 0 points
• Promoter Holdings: >=50% = 2 points, 30-50% = 1 point, <30% = 0 points

Growth Categories:

• 0-4 Points: 🔴 Weak
• 5-7 Points: 🟡 Neutral
• 8-10 Points: 🟢 Growth

---

📁 Project Structure

StocksMCP/
├── requirements.txt            # Python dependencies (fastmcp, yfinance, fastapi, etc.)
├── .env.example                # Template for server & dashboard config
├── .gitignore                  # Git rules (ignoring .env and reports/*.json)
├── reports/                    # Directory where local JSON reports are saved
│   └── NATIONALUM_NS.json      # Sample generated report
├── src/
│   ├── __init__.py             # Package init
│   ├── server.py               # FastMCP Server containing tool endpoints
│   ├── client.py               # MCP client agent running automatic pipelines
│   ├── data_fetcher.py         # yfinance scraper & parser
│   ├── analyzer.py             # Computes fair value, growth scores, & AI summaries
│   ├── dashboard.py            # Prefab UI layout compiler
│   └── web_dashboard.py        # FastAPI server backend
└── templates/
    └── dashboard.html          # HTML5 terminal dashboard with Plotly charts

---

📈 Verification Checklist

To verify all requirements are met:

1. Tool 1: fetch_stock_data: Call fetch_stock_data("NATIONALUM.NS") → returns raw stock fundamentals, financials, and historical price history.
2. Tool 2: save_stock_report: Call save_stock_report("NATIONALUM", report) → creates reports/NATIONALUM_NS.json with calculated metrics, AI summary, and raw data.
3. Tool 3: show_dashboard: Call show_dashboard("NATIONALUM.NS") → registers and returns structural generative UI.
4. CRUD CRUD CRUD: Test update/delete tools (update_stock_report and delete_stock_report).
5. FastAPI Web Server: Run python3 -m src.web_dashboard and inspect interactive elements at http://localhost:8000.