IndiaQuant MCP

Real-time Indian stock market AI assistant built on Model Context Protocol (MCP). Plugs into Claude Desktop (or any MCP-compatible AI agent) to provide full stock market intelligence + virtual trading capabilities using 100% free APIs.

---

Architecture

┌─────────────────────────────────────────────────┐
│               Claude Desktop (Client)            │
│  "Should I buy HDFC Bank right now?"             │
└──────────────────┬──────────────────────────────┘
                   │ MCP Protocol (stdio / SSE)
                   ▼
┌─────────────────────────────────────────────────┐
│            server.py — MCP Tools Layer           │
│  10 registered tools with JSON schemas           │
│  Routes requests → modules                       │
└──────┬───────┬───────┬───────┬──────────────────┘
       │       │       │       │
       ▼       ▼       ▼       ▼
┌────────┐┌────────┐┌────────┐┌────────┐
│ Market ││ Signal ││Options ││Portfol-│
│ Data   ││ Gener- ││ Chain  ││io Risk │
│ Engine ││ ator   ││Analyzer││Manager │
└───┬────┘└───┬────┘└───┬────┘└───┬────┘
    │         │         │         │
    ▼         ▼         ▼         ▼
 yfinance  NewsAPI   yfinance   SQLite
 Alpha V.  VADER     Black-
           pandas-ta Scholes

5 Modules

Module	File	Purpose
Market Data Engine	modules/market_data.py	Live prices, historical OHLCV, sector heatmap, market scanner via yfinance
Signal Generator	modules/signal_generator.py	RSI/MACD/Bollinger via pandas-ta, VADER sentiment on NewsAPI headlines, weighted BUY/SELL/HOLD signal
Options Chain Analyzer	modules/options_analyzer.py	Options chain via yfinance, max pain calculation, OI spike detection, unusual activity alerts
Black-Scholes Greeks	modules/black_scholes.py	Pure mathematical Black-Scholes: Delta, Gamma, Theta, Vega, IV — no pricing libraries
Portfolio Risk Manager	modules/portfolio_manager.py	Virtual portfolio in SQLite, live P&L, stop-loss/target tracking, volatility-based risk scoring

10 MCP Tools

#	Tool	Input	Output
1	tool_get_live_price	symbol	price, change%, volume
2	tool_get_options_chain	symbol, expiry	strikes, CE/PE OI, max pain, PCR
3	tool_analyze_sentiment	symbol	score, headlines, signal
4	tool_generate_signal	symbol, timeframe	BUY/SELL/HOLD, confidence
5	tool_get_portfolio_pnl	—	positions, total P&L
6	tool_place_virtual_trade	symbol, qty, side	order_id, status
7	tool_calculate_greeks	symbol, strike, expiry, type	delta, gamma, theta, vega
8	tool_detect_unusual_activity	symbol	alerts, anomalies
9	tool_scan_market	filter criteria	matching symbols
10	tool_get_sector_heatmap	—	sectors with % change

---

Free API Stack

Purpose	API	Limits
Live NSE/BSE prices	yfinance	Unlimited, free
Historical OHLC	yfinance	Full history, free
Options chain	yfinance	Free, NSE supported
News & sentiment	NewsAPI.org	100 req/day free
Macro indicators	Alpha Vantage	25 req/day free
Technical analysis	pandas-ta	Fully free, open source
Greeks calculation	Custom Black-Scholes	From scratch

---

Setup Guide

Prerequisites

• Python 3.11+
• Claude Desktop installed

1. Clone & Install

git clone https://github.com/YOUR_USERNAME/indiaquant-mcp.git
cd indiaquant-mcp

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.venv\Scripts\activate
# Activate (macOS/Linux)
source .venv/bin/activate

# Install dependencies
pip install -e ".[dev]"

2. Get API Keys (Free)

1. NewsAPI: Register at newsapi.org → get free key
2. Alpha Vantage: Get key at alphavantage.co

3. Configure Environment

cp .env.example .env
# Edit .env with your API keys

4. Connect to Claude Desktop

Edit Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add this to the config:

{
  "mcpServers": {
    "indiaquant": {
      "command": "python",
      "args": ["C:\\FULL\\PATH\\TO\\indiaquant-mcp\\server.py"],
      "env": {
        "NEWSAPI_KEY": "your_key_here",
        "ALPHA_VANTAGE_KEY": "your_key_here"
      }
    }
  }
}

Important: Use the full absolute path to server.py. On Windows, use double backslashes.

5. Restart Claude Desktop

Close and reopen Claude Desktop. You should see a 🔧 (hammer) icon in the chat input box — click it to verify all 10 IndiaQuant tools are listed.

6. Test It

Ask Claude:

• "What's the live price of Reliance?"
• "Generate a signal for HDFC Bank"
• "Buy 10 shares of TCS"
• "Show my portfolio P&L"
• "What's the max pain for Nifty?"

---

Running Tests

# Run all tests
pytest tests/ -v

# Run only Black-Scholes tests (offline, no API needed)
pytest tests/test_black_scholes.py -v

# Run signal/tool tests (needs internet)
pytest tests/test_signals.py tests/test_tools.py -v

---

Deploy on Render (24/7 Availability)

See the Deployment Guide section below for full step-by-step instructions.

Quick Steps

1. Push code to GitHub
2. Create a new Web Service on render.com
3. Connect your GitHub repo
4. Set build command: pip install -e .
5. Set start command: python server.py --transport sse
6. Add environment variables (API keys)
7. Deploy

Then update Claude Desktop config to use the SSE endpoint:

{
  "mcpServers": {
    "indiaquant": {
      "url": "https://your-app.onrender.com/sse"
    }
  }
}

---

Design Decisions & Trade-offs

Caching Strategy

• 30s TTL for live prices — balances freshness vs. rate limits
• 5min TTL for options chain — chains don't change drastically
• 1hr TTL for news sentiment — avoid burning NewsAPI free quota
• In-memory (cachetools) — simple, no Redis needed for single-server

Signal Confidence Scoring

• 40% technicals (RSI, MACD, Bollinger) — most reliable for short-term
• 30% sentiment (VADER on news headlines) — captures market mood
• 30% trend/patterns (SMA crossovers, chart patterns) — confirms direction
• Score maps to 0–100 confidence via distance from neutral (50)

Black-Scholes Implementation

• Pure math with scipy.stats.norm for CDF/PDF only (standard normal distribution)
• Newton-Raphson for implied volatility calculation
• Per-day theta (divided by 365) for practical use
• Vega per 1% volatility change for readability

Portfolio Manager

• SQLite for zero-config persistence — portfolio survives restarts
• Position averaging on repeated buys of same stock
• Risk score based on annualized historical volatility (3-month window)

Edge Case Handling

• Market holidays: yfinance returns last available data, cache prevents redundant calls
• Missing data: graceful fallbacks (signal works on technicals alone if news API fails)
• Symbol normalization: auto-appends .NS, handles indices like NIFTY → ^NSEI

---

Project Structure

indiaquant-mcp/
├── server.py                  # MCP server entry point (10 tools)
├── config.py                  # API keys, constants, sector maps
├── pyproject.toml             # Dependencies
├── .env.example               # Environment template
├── .gitignore
├── README.md
├── modules/
│   ├── __init__.py
│   ├── market_data.py         # Module 1: yfinance + caching
│   ├── signal_generator.py    # Module 2: TA + sentiment
│   ├── options_analyzer.py    # Module 3: chain + Greeks
│   ├── black_scholes.py       # Pure Black-Scholes implementation
│   ├── portfolio_manager.py   # Module 4: SQLite + risk
│   └── cache.py               # TTL cache wrapper
└── tests/
    ├── __init__.py
    ├── test_black_scholes.py   # Greeks math validation
    ├── test_signals.py         # Signal generator tests
    └── test_tools.py           # Integration tests

---

License

MIT