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

10 MCP Tools

Free API Stack

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