🇮🇳 India Stock MCP Server

A production-ready Model Context Protocol (MCP) server that gives AI assistants like Claude, Cursor and VS Code Copilot live access to Indian stock market data from NSE and BSE: quotes, price history, technical indicators, fundamentals and market indices.

It runs over Streamable HTTP, so anyone can connect to the hosted server with just a URL. Nothing to install.

⚠️ Not investment advice. This project is for education and research. Data may be delayed (~15 minutes) and may contain errors. Always do your own research before making investment decisions.

✨ Tools

There is also a prompt, analyze_stock, that runs a complete analysis of one stock.

Symbols are NSE trading symbols such as RELIANCE, TCS, INFY, HDFCBANK, M&M or BAJAJ-AUTO.

Related MCP server: nse-mcp

🚀 Connect to the hosted server

Server URL: https://YOUR-APP.onrender.com/mcp

Settings → Connectors → Add custom connector → paste the server URL.

claude mcp add --transport http india-stocks https://YOUR-APP.onrender.com/mcp

{
  "mcpServers": {
    "india-stocks": { "url": "https://YOUR-APP.onrender.com/mcp" }
  }
}

{
  "servers": {
    "india-stocks": { "type": "http", "url": "https://YOUR-APP.onrender.com/mcp" }
  }
}

The free hosting tier sleeps when idle, so the first request after a quiet period can take ~30–60 seconds.

🏗️ Architecture

AI client ──HTTPS POST /mcp──▶ Rate limiter ──▶ MCP server (stateless) ──▶ Tool
                                (60 req/min/IP)                              │
                                                       TTL cache ◀──────────┤
                                                           │ miss            │
                                                           ▼                 │
                                                   Yahoo Finance ──(retry)──┘

• Stateless Streamable HTTP: every request is independent, so the server scales horizontally.

• TTL caching: quotes 1 min, price history 15 min, fundamentals 6 h. Popular stocks cost one upstream call.

• Retries with backoff: transient Yahoo failures are retried; real outages return a clear message.

• Per-client rate limiting: token bucket keyed on client IP, resistant to forged X-Forwarded-For headers.

• Input validation: symbols, periods and intervals are validated before any network call.

💻 Run it locally

Requires uv and Python 3.11+.

git clone https://github.com/DiwakarReddy11/india-stock-mcp.git
cd india-stock-mcp
uv sync
uv run python -m india_stock_mcp.server

The server starts at http://127.0.0.1:8000/mcp. Check it with:

curl http://127.0.0.1:8000/health          # {"status":"ok"}
uv run python scripts/smoke_test.py        # calls every tool

With Docker

docker build -t india-stock-mcp .
docker run -d --name india-stock-mcp -p 8000:8000 india-stock-mcp

⚙️ Configuration

All settings are environment variables (or a .env file; see .env.example).

🧪 Development

uv sync                                   # installs dev tools too
uv run pytest                             # 36 offline tests (Yahoo is mocked)
uv run ruff check src scripts tests       # lint
uv run ruff format src scripts tests      # format

Project structure

src/india_stock_mcp/
├── server.py      # MCP server, tools, data fetching, indicators
├── config.py      # settings from environment variables
└── ratelimit.py   # per-client rate limiting middleware
tests/             # offline test suite
scripts/           # smoke test against a running server
Dockerfile         # multi-stage, non-root production image

⚠️ Limitations

• Data source: prices come from Yahoo Finance via yfinance, an unofficial API intended for personal and research use. Data can be delayed or temporarily unavailable. For commercial use, switch to a licensed provider (e.g. a broker API).

• BSE: use trading symbols with exchange="BSE" (e.g. RELIANCE), not numeric scrip codes. Yahoo's BSE history is often limited, so previous close and technical analysis work best on NSE.

• Market status uses regular trading hours (Mon–Fri 09:15–15:30 IST) and does not know exchange holidays.

• Rate limits are per server instance (in memory).

📄 License

MIT © 2026 DiwakarReddy

Disclaimer: This software is provided for informational and educational purposes only and does not constitute financial, investment or trading advice. The authors accept no liability for any losses arising from its use.