# india-stock-mcp

[![CI](https://github.com/Akhilgovind02/india-stock-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Akhilgovind02/india-stock-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/india-stock-mcp)](https://www.npmjs.com/package/india-stock-mcp)

MCP server for Indian stock market data — NSE/BSE quotes, historical prices, fundamentals, mutual fund NAV, indices, corporate actions, F&O option chains, IPOs, and portfolio analysis.

Works with any MCP client: Claude Desktop, Claude Code, Cursor, etc. **No API keys, no auth, all free data sources.**

## Tools (16)

| Tool | What it does |
|---|---|
| `get_quote` | Live price, volume, 52-week range for NSE/BSE stocks and indices |
| `get_historical` | OHLCV history — daily / weekly / monthly |
| `search_symbol` | Find stock symbols by company name |
| `get_fundamentals` | P/E, EPS, ROE, margins, debt, growth rates |
| `compare_stocks` | 2–5 stocks side by side |
| `get_index` | Any NSE index (P/E, P/B, advances/declines) + SENSEX |
| `get_market_status` | Is the market open? Session info per segment |
| `get_gainers_losers` | Top NIFTY 50 movers ranked by % change |
| `get_corporate_actions` | Dividends, splits, bonuses — per stock or market-wide |
| `get_options_chain` | F&O chain around ATM: LTP, OI, OI change, IV, volume |
| `get_ipo_list` | Current / upcoming / recently listed IPOs |
| `search_funds` | Search 15,000+ Indian mutual fund schemes |
| `get_fund_nav` | NAV history for a scheme |
| `get_fund_details` | Fund house, category, current NAV |
| `compare_funds` | 2–4 funds: NAV + % return over any period |
| `portfolio_summary` | Holdings → current value, P&L, allocation breakdown |

## Requirements

- Node.js 22+

## Setup

### Via npm (recommended)

No clone, no build:

**Claude Code**
```bash
claude mcp add india-stock -- npx -y india-stock-mcp
```

**Claude Desktop** — add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):

```json
{
  "mcpServers": {
    "india-stock": {
      "command": "npx",
      "args": ["-y", "india-stock-mcp"]
    }
  }
}
```

### From source

```bash
git clone https://github.com/Akhilgovind02/india-stock-mcp.git
cd india-stock-mcp
npm install
npm run build
claude mcp add india-stock -- node /absolute/path/to/india-stock-mcp/dist/index.js
```

Restart Claude Desktop fully, then look for the tools icon in a new chat.

### Example prompts

- "Quote for RELIANCE and how far is it from its 52-week high?"
- "Compare HDFC Bank vs ICICI Bank vs SBI fundamentals"
- "Top 5 NIFTY 50 gainers today"
- "NIFTY option chain — where's the max open interest?"
- "Compare Parag Parikh Flexi Cap vs Quant Small Cap over 3 years"
- "Analyze my portfolio: 10 RELIANCE @ 1200, 5 TCS @ 3000"

## Development

```bash
npm run dev                      # run from TypeScript directly
npx tsx scripts/test-mcp.ts      # end-to-end test of all 16 tools (live data)
npx tsx scripts/test-edge.ts     # 24 edge-case assertions
npm run build                    # compile to dist/
```

### Sample test output

Real output from `npx tsx scripts/test-mcp.ts` (live data, market hours, June 2026 — trimmed):

```
TOOLS: get_quote, get_historical, search_symbol, search_funds, get_fund_nav,
get_fundamentals, compare_stocks, get_index, get_market_status, get_gainers_losers,
get_corporate_actions, get_options_chain, get_ipo_list, get_fund_details,
compare_funds, portfolio_summary

PASS get_quote: {"source":"Yahoo Finance","symbol":"RELIANCE.NS","name":"RELIANCE
  INDUSTRIES LTD","price":1266,"changePct":0.23,"volume":6107188,...}
PASS get_index: {"source":"NSE","index":"NIFTY BANK","last":55915,"percentChange":1.34,
  "yearHigh":61764.85,"pe":...}
PASS get_market_status: [{"market":"Capital Market","marketStatus":"Open",...}]
PASS get_gainers_losers: {"type":"gainers","universe":"NIFTY 50","data":[{"symbol":
  "SHRIRAMFIN","changePct":3.17,...}]}
PASS get_corporate_actions: {"symbol":"RELIANCE","actions":[{"subject":"Dividend -
  Rs 5.5 Per Share","exDate":"14-Aug-2025",...}]}
PASS get_options_chain: {"symbol":"NIFTY","underlyingValue":23331,"atmStrike":23350,
  "availableExpiries":["16-Jun-2026",...],"data":[{"strikePrice":...,"CE":{"lastPrice":
  130.95,"openInterest":144769,"impliedVolatility":12.26},...}]}
PASS get_ipo_list: {"type":"current","ipos":[{"companyName":"Utkal Speciality
  Industries India Limited","status":"Active",...}]}
PASS compare_funds: {"comparison":[{"name":"Parag Parikh Flexi Cap Fund - Direct
  Plan - Growth","latestNAV":88.484,...}]}
PASS portfolio_summary: {"summary":{"totalInvested":41000,"totalCurrentValue":38663,
  "totalPnL":-2337,"totalPnLPct":-5.7,...}}

... all 16 tools PASS
```

## Data sources

| Source | Used for | Notes |
|---|---|---|
| Yahoo Finance (`yahoo-finance2`) | Quotes, history, fundamentals, search | Primary source, may be delayed a few minutes |
| NSE India (`nse-bse-api`) | Market status, indices, corporate actions, IPOs, option chains | Some NSE endpoints (quote, autocomplete) are no longer publicly accessible — the server falls back to Yahoo automatically |
| [mfapi.in](https://www.mfapi.in) | Mutual fund NAV and search | Free, occasionally flaky — requests retry once |
| [mfdata.in](https://mfdata.in) | Fund ratings / expense ratio | Often unreachable; falls back to mfapi.in |

### Known limitations

- `get_gainers_losers` ranks a built-in NIFTY 50 constituent list (verified June 2026). NSE reconstitutes the index ~2×/year — update `NIFTY50_SYMBOLS` in `src/index.ts` when that happens.
- Quotes may be delayed (Yahoo free feed); not suitable for live trading decisions.
- NSE may rate-limit or block heavy usage.

## Disclaimer

Data comes from free public sources and may be delayed, incomplete, or wrong. This is not financial advice and not a substitute for a licensed broker or advisor. Do your own research before trading or investing.

## License

[MIT](LICENSE)