NSE MCP Explorer

NSE MCP Explorer — learn, explore & build with the NSE India MCP servers

An open-source NSE MCP client, playground and tutorial for the National Stock Exchange of India’s official Model Context Protocol (MCP) servers — live NSE stock quotes, top gainers/losers, 5-year Bhavcopy price history, market breadth, corporate actions, analytics and an AI-agent demo, with TypeScript and Python examples for Claude, ChatGPT and your own apps.

Heard about NSE MCP but don’t know where to start? This repository is an interactive playground and guide for the official NSE India MCP servers. In about ten minutes you can understand what MCP is, connect to NSE, run every tool it offers, inspect the raw protocol messages, and see what you can build with the data.

npm install
npm run dev          # → http://localhost:5180   (live NSE data, no API key needed)
npm run dev:mock     # offline: recorded NSE responses

Requires Node.js 22.12+.

What is NSE MCP? (30-second version)

MCP (Model Context Protocol) is an open standard that lets apps and AI assistants discover and call “tools” on a server — JSON-RPC messages over HTTP.
NSE (National Stock Exchange of India) runs two free, public MCP servers — no login, no API key:

Server	URL	What it gives you
CM Market Live	`https://mcp.nseindia.in/cmmkt/mcp`	Quotes, gainers/losers and segment listings, 1–5 min delayed
NSE Bhavcopy	`https://mcp.nseindia.in/bhavcopy/cm/mcp`	5 years of end-of-day prices, breadth, movers, volume analysis, SMA, 52-week range, comparisons, corporate actions

Together they expose 26 tools (full matrix). No derivatives, option chains, index levels, announcements or delivery data (details).

What’s in the app

Page	You get
1 · What is MCP?	Client / server / tools explained from zero, how a session works, MCP vs a REST API
2 · Connect	Live connection status, server info, protocol version, tool counts, errors
3 · Tool explorer	All 26 tools, searchable; forms generated from each tool’s schema; results as charts/tables plus parsed data, the MCP result, the raw JSON-RPC, and ready-to-copy TypeScript/Python/curl
4 · Examples	17 guided, runnable examples: goal → tool → request → response → interpretation → how to build it
5 · Build: insights	Mini-apps composed from several tools + analytics: stock deep dive (split/bonus-adjusted, SMA/EMA/RSI, volatility, drawdown), movers with unusual volume, breadth trend, peer comparison
6 · Integrate	Configs for Claude Desktop, Claude connectors, ChatGPT, VS Code, stdio bridges; code for any tool
AI agent demo (optional)	Claude picks NSE tools by itself to answer a question (needs `ANTHROPIC_API_KEY`)
Protocol log	Every JSON-RPC message exchanged with NSE

Use NSE MCP without this app

In Claude Desktop — add to claude_desktop_config.json (from NSE’s own instructions):

{
  "mcpServers": {
    "cm-market":    { "url": "https://mcp.nseindia.in/cmmkt/mcp",       "transport": "streamable-http" },
    "nse-bhavcopy": { "url": "https://mcp.nseindia.in/bhavcopy/cm/mcp", "transport": "streamable-http" }
  }
}

From code (TypeScript, official SDK):

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('https://mcp.nseindia.in/cmmkt/mcp')));
const result = await client.callTool({ name: 'cm_get_stock_quote', arguments: { symbol: 'RELIANCE' } });
const data = JSON.parse((result.content as { text: string }[])[0].text);
if (data.error) throw new Error(data.error);   // NSE reports errors inside successful results

Runnable programs: examples/typescript, examples/python, client configs in examples/config.

Five things every NSE MCP developer should know

Errors hide inside successes — check for an error key even when isError is false.
Prices are unadjusted — splits/bonuses look like crashes; use get_corporate_actions.
Bad dates don’t fail — they silently return the latest trading day; read the returned date.
Browsers can’t call it directly — CORS allows only NSE’s sites; use a backend.
It’s a free public service — cache, space out requests, expect occasional timeouts. Data is for educational/informational use only (no commercial use, no AI training) — not investment advice.

Architecture in one picture

Browser (React)  ──/api──▶  Node backend = MCP client  ──Streamable HTTP──▶  mcp.nseindia.in (2 servers)
                            hub · validation · cache · wiretap · analytics · optional agent
                                                    └── or mock MCP server (recorded fixtures)

TypeScript end-to-end; analytics are small pure functions (no Pandas needed). See ARCHITECTURE.md.

Commands


`npm run dev` / `npm run dev:mock`	Develop against live NSE / the mock
`npm run build` then `npm start`	Production build and server
`npm test`	Offline test suite (72 tests)
`npm run test:live`	Smoke test against real NSE
`npm run example:ts`	TypeScript quickstart
`npm run record-fixtures`	Refresh mock data from live NSE

Configuration is optional — see .env.example.

Documentation

Doc
GETTING_STARTED.md	Step-by-step first run
NSE_MCP_RESEARCH.md	What we verified about NSE MCP: transport, auth, sessions, CORS, throttling, quirks
NSE_MCP_CAPABILITIES.md	Every tool: parameters, responses, implementation/test status
EXAMPLES.md	The 17 guided examples + recipes
ARCHITECTURE.md	Design decisions and components
DEVELOPMENT.md	Layout, scripts, conventions, extending
TESTING.md	What was tested, live results, limitations
TROUBLESHOOTING.md	Timeouts, soft errors, date fallbacks, Python SDK changes

Disclaimer

This is an independent educational project, not affiliated with or endorsed by NSE. Data returned by NSE MCP belongs to NSE and is provided for informational and educational purposes only, subject to NSE’s terms. Nothing here is investment advice. Code is MIT-licensed (LICENSE).

This site is open source. Improve this page.