io.github.Akhilgovind02/india-stock-mcp

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

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\):

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

From source

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

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	Mutual fund NAV and search	Free, occasionally flaky — requests retry once
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