mcp server

NSE-MCP

NSE/BSE MCP Server for Indian stock market data

icharshal/NSE-MCPcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

Node.js 20 or newer

~/Library/Application Support/Claude/claude_desktop_config.json

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

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 26, 2026

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:

Fetches https://www.nseindia.com to obtain initial cookies.
Fetches the live-equity-market page with those cookies to complete the session.
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