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:

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

Related MCP server: Indian Stock Exchange API2 MCP Server

Requirements

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:

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.

get_block_deals

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

get_insider_trading

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

get_latest_bulk_deals

Today's bulk deals sorted by trade value.

get_top_bulk_buys

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

get_top_bulk_sells

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

get_fii_dii_activity

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

get_nse_announcements

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

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.

get_top_gainers

Top gaining stocks by % change in the current session.

get_top_losers

Top losing stocks by % change in the current session.

get_most_active

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

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.

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.

get_short_selling

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

get_corporate_actions

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

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

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

License

MIT