Nse Mcp Explorer

CI License: MIT

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

1. Errors hide inside successes — check for an error key even when isError is false.
2. Prices are unadjusted — splits/bonuses look like crashes; use get_corporate_actions.
3. Bad dates don't fail — they silently return the latest trading day; read the returned date.
4. Browsers can't call it directly — CORS allows only NSE's sites; use a backend.
5. 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).