NSE MCP

An MCP (Model Context Protocol) server that exposes live Indian stock market data from the National Stock Exchange (NSE) to LLM clients like Claude Desktop, Cursor, VS Code, and any other MCP-compatible host.

Modelled after OpenInsider-MCP but built entirely around NSE India's public data APIs.

---

What it provides

17 tools across five categories:

Category	Tools
Bulk / Block / Insider deals	get_bulk_deals, get_block_deals, get_insider_trading, get_latest_bulk_deals, get_top_bulk_buys, get_top_bulk_sells, search_by_symbol
Institutional flows	get_fii_dii_activity
Market data	get_quote, get_market_status, get_nifty_indices, get_top_gainers, get_top_losers, get_most_active
Corporate events	get_nse_announcements, get_corporate_actions
Short data	get_short_selling

All tools return typed JSON. No scoring, no recommendations — pure data layer.

---

Requirements

Requirement	Version
Node.js	≥ 20
npm	≥ 8 (bundled with Node 20)
Git	Any recent version

Why Node 20? The server uses the native fetch API and AbortSignal.timeout(), both of which require Node 18+. Node 20 is the active LTS and is recommended.

---

Installation

1. Clone the repository

git clone https://github.com/manitgupta/nse-mcp.git
cd nse-mcp

2. Install dependencies

npm install

3. Build

npm run build

This compiles the TypeScript source in src/ to dist/. The entry point is dist/index.js.

4. Verify it starts

node dist/index.js

The server communicates over stdio (standard input/output) — it will appear to hang because it is waiting for MCP messages. That is correct. Press Ctrl+C to exit.

---

Configuration

The server works out of the box with no required configuration. One optional environment variable is available:

Variable	Default	Description
NSE_MCP_UA	Chrome 120 UA string	Override the User-Agent sent to NSE and Yahoo Finance. Useful if NSE starts blocking the default UA.

Setting the environment variable

macOS / Linux

export NSE_MCP_UA="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/121.0.0.0 Safari/537.36"

Windows (PowerShell)

$env:NSE_MCP_UA = "Mozilla/5.0 ..."

You can also set it inline in your MCP client config (see below).

How NSE session auth works

NSE India's API requires browser-like cookies. On the first request the server automatically:

1. Fetches https://www.nseindia.com to obtain initial cookies.
2. Fetches the live-equity-market page with those cookies to complete the session.
3. Caches the session for ~7 minutes, then refreshes transparently.

No manual login or API key is needed.

---

Adding to an MCP client

In all configs below, replace /absolute/path/to/nse-mcp with the actual path where you cloned the repo.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "nse-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/nse-mcp/dist/index.js"]
    }
  }
}

With an env override:

{
  "mcpServers": {
    "nse-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/nse-mcp/dist/index.js"],
      "env": {
        "NSE_MCP_UA": "Mozilla/5.0 ..."
      }
    }
  }
}

Restart Claude Desktop after saving.

VS Code (GitHub Copilot / Continue)

Add to .vscode/mcp.json in your workspace, or to your user settings:

{
  "servers": {
    "nse-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/nse-mcp/dist/index.js"]
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "nse-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/nse-mcp/dist/index.js"]
    }
  }
}

Any stdio-based MCP host

command: node
args:    ["/absolute/path/to/nse-mcp/dist/index.js"]

---

Tool reference

get_bulk_deals

Today's NSE bulk deals — single-client trades of ≥ 0.5% of a company's listed shares in one session.

Parameter	Type	Description
symbol	string	NSE symbol (e.g. RELIANCE). Omit for all.
dealType	BUY | SELL | ALL	Direction filter. Default: ALL.

---

get_block_deals

Today's NSE block deals — negotiated trades of minimum ₹10 crore executed in the Block Deal Window.

Parameter	Type	Description
symbol	string	NSE symbol. Omit for all.
dealType	BUY | SELL | ALL	Direction filter. Default: ALL.

---

get_insider_trading

SEBI PIT (Prohibition of Insider Trading) disclosures — promoter and insider buy/sell transactions.

Parameter	Type	Description
symbol	string	NSE symbol. Omit for all companies.
fromDate	string	YYYY-MM-DD. Default: 30 days ago.
toDate	string	YYYY-MM-DD. Default: today.

---

get_latest_bulk_deals

Today's bulk deals sorted by trade value.

Parameter	Type	Description
dealType	BUY | SELL | ALL	Direction filter. Default: ALL.

---

get_top_bulk_buys

Largest bulk-deal purchases today, ranked by total value (quantity × price).

Parameter	Type	Description
limit	number	Results to return. Default: 10.
symbol	string	Restrict to one symbol.

---

get_top_bulk_sells

Largest bulk-deal sales today, ranked by total value.

Parameter	Type	Description
limit	number	Results to return. Default: 10.
symbol	string	Restrict to one symbol.

---

get_fii_dii_activity

Daily FII and DII net buy/sell figures in the Indian cash market.

Parameter	Type	Description
limit	number	Number of recent trading days. Default: 10.

---

get_nse_announcements

Corporate announcements filed with NSE — board meetings, results, mergers, regulatory updates, etc. (equivalent to SEC 8-K filings).

Parameter	Type	Description
symbol	string	NSE symbol. Omit for all.
daysBack	number	Announcements from the last N days. Omit for no date filter.
limit	number	Maximum results. Default: 20.

---

get_market_status

Current open/closed status of NSE segments (Capital Market, F&O, Currency Derivatives, Commodity) plus live index levels.

No parameters.

---

get_nifty_indices

Live data for all NSE indices — price, change, 52-week range, advances/declines count.

Parameter	Type	Description
name	string	Partial, case-insensitive filter. E.g. "BANK" returns all bank-related indices.

---

get_top_gainers

Top gaining stocks by % change in the current session.

Parameter	Type	Description
index	string	NSE index to scan. Default: NIFTY 500.
limit	number	Results to return. Default: 10.

---

get_top_losers

Top losing stocks by % change in the current session.

Parameter	Type	Description
index	string	NSE index to scan. Default: NIFTY 500.
limit	number	Results to return. Default: 10.

---

get_most_active

Most actively traded stocks by total traded value (₹) in the current session.

Parameter	Type	Description
index	string	NSE index to scan. Default: NIFTY 500.
limit	number	Results to return. Default: 10.

---

search_by_symbol

Aggregated view for one stock — returns today's bulk deals, block deals, recent insider trades, and recent announcements in a single call.

Parameter	Type	Description
symbol	string	NSE symbol. Required.
daysBack	number	Look-back window for insider trades and announcements. Default: 30.

---

get_quote

Live stock quote via Yahoo Finance. Returns price, 52-week range, volume, market cap, P/E ratios, dividend yield, and next earnings date. Prices are in INR.

Parameter	Type	Description
symbol	string	NSE symbol (e.g. RELIANCE, TCS). .NS exchange suffix is appended automatically. Pass SYMBOL.BO to query BSE instead. Required.

---

get_short_selling

Short-selling data as reported by brokers to NSE under SEBI's short-selling framework.

Parameter	Type	Description
symbol	string	NSE symbol. Omit for all.
limit	number	Return top N stocks by short-sold quantity.

---

get_corporate_actions

Upcoming and recent corporate actions — dividends, stock splits, bonus issues, rights issues, buy-backs.

Parameter	Type	Description
symbol	string	NSE symbol. Omit for all companies.
fromDate	string	YYYY-MM-DD. Default: 3 months ago.
toDate	string	YYYY-MM-DD. Default: today.

---

Example prompts

Once configured, you can ask your LLM client things like:

• "What are today's biggest bulk deals on NSE?"
• "Show me insider trades for RELIANCE in the last 30 days."
• "What is the live quote for TCS?"
• "Which Nifty 50 stocks are up more than 2% today?"
• "What's the FII/DII flow for the last 5 trading days?"
• "Give me all corporate actions for INFY this quarter."
• "Show everything you know about HDFC — deals, announcements, insider activity."

---

Development

# Watch mode — recompiles on every save
npm run dev

# One-shot build
npm run build

# Start the compiled server
npm start

Project structure

src/
├── index.ts          # MCP server entry point — tool list + dispatch
├── types.ts          # Shared TypeScript interfaces
├── cache.ts          # In-memory TTL cache
├── http.ts           # Rate-paced HTTP fetcher with retry
├── nse/
│   ├── session.ts    # NSE cookie session management
│   └── fetch.ts      # NSE API client (wraps http.ts + session)
├── yahoo/
│   ├── fetch.ts      # Yahoo Finance HTTP config
│   ├── parseQuote.ts # Quote JSON parser
│   └── quoteSummary.ts
└── tools/            # One file per tool
    ├── bulkDeals.ts
    ├── blockDeals.ts
    ├── insiderTrading.ts
    ├── latestBulkDeals.ts
    ├── topBulkBuys.ts
    ├── topBulkSells.ts
    ├── fiiDiiActivity.ts
    ├── announcements.ts
    ├── marketStatus.ts
    ├── indices.ts
    ├── topGainers.ts
    ├── topLosers.ts
    ├── mostActive.ts
    ├── searchBySymbol.ts
    ├── quote.ts
    ├── shortSelling.ts
    └── corporateActions.ts

---

Data sources

Data	Source
Bulk deals, block deals, insider trading, FII/DII, indices, market status, announcements, corporate actions, short selling	NSE India public API (nseindia.com)
Live stock quotes	Yahoo Finance (.NS suffix for NSE, .BO for BSE)

All data is fetched in real time. NSE endpoints are cached for 5 minutes; live quotes and market status for 60 seconds.

---

License

MIT