{"id":"d9ace83c-2cb8-40f0-9953-81922b1bdc5f","slug":"nse-mcp","kind":"mcp","name":"NSE-MCP","summary":"NSE/BSE MCP Server for Indian stock market data","owner":"icharshal","repoUrl":"https://github.com/icharshal/NSE-MCP","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-07-28T09:02:26.000Z","addedAt":"2026-10-21T21:37:04.969Z","logoUrl":"https://avatars.githubusercontent.com/u/69721177?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics","cloud-infra"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T04:20:09.406Z","sample":false,"url":"https://conduits.dev/tools/nse-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"nse-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# NSE MCP\n\nAn [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 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.\n\nModelled after [OpenInsider-MCP](https://github.com/btopn/OpenInsider-MCP) but built entirely around NSE India's public data APIs.\n\n---\n\n## What it provides\n\n17 tools across five categories:\n\n| Category | Tools |\n|---|---|\n| 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` |\n| Institutional flows | `get_fii_dii_activity` |\n| Market data | `get_quote`, `get_market_status`, `get_nifty_indices`, `get_top_gainers`, `get_top_losers`, `get_most_active` |\n| Corporate events | `get_nse_announcements`, `get_corporate_actions` |\n| Short data | `get_short_selling` |\n\nAll tools return typed JSON. No scoring, no recommendations — pure data layer.\n\n---\n\n## Requirements\n\n| Requirement | Version |\n|---|---|\n| Node.js | **≥ 20** |\n| npm | ≥ 8 (bundled with Node 20) |\n| Git | Any recent version |\n\n> **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.\n\n---\n\n## Installation\n\n### 1. Clone the repository\n\n```bash\ngit clone https://github.com/manitgupta/nse-mcp.git\ncd nse-mcp\n```\n\n### 2. Install dependencies\n\n```bash\nnpm install\n```\n\n### 3. Build\n\n```bash\nnpm run build\n```\n\nThis compiles the TypeScript source in `src/` to `dist/`. The entry point is `dist/index.js`.\n\n### 4. Verify it starts\n\n```bash\nnode dist/index.js\n```\n\nThe 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.\n\n---\n\n## Configuration\n\nThe server works out of the box with no required configuration. One optional environment variable is available:\n\n| Variable | Default | Description |\n|---|---|---|\n| `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. |\n\n### Setting the environment variable\n\n**macOS / Linux**\n```bash\nexport NSE_MCP_UA=\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/121.0.0.0 Safari/537.36\"\n```\n\n**Windows (PowerShell)**\n```powershell\n$env:NSE_MCP_UA = \"Mozilla/5.0 ...\"\n```\n\nYou can also set it inline in your MCP client config (see below).\n\n### How NSE session auth works\n\nNSE India's API requires browser-like cookies. On the first request the server automatically:\n1. Fetches `https://www.nseindia.com` to obtain initial cookies.\n2. Fetches the live-equity-market page with those cookies to complete the session.\n3. Caches the session for ~7 minutes, then refreshes transparently.\n\nNo manual login or API key is needed.\n\n---\n\n## Adding to an MCP client\n\nIn all configs below, replace `/absolute/path/to/nse-mcp` with the actual path where you cloned the repo.\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"nse-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/nse-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\nWith an env override:\n\n```json\n{\n  \"mcpServers\": {\n    \"nse-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/nse-mcp/dist/index.js\"],\n      \"env\": {\n        \"NSE_MCP_UA\": \"Mozilla/5.0 ...\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after saving.\n\n### VS Code (GitHub Copilot / Continue)\n\nAdd to `.vscode/mcp.json` in your workspace, or to your user settings:\n\n```json\n{\n  \"servers\": {\n    \"nse-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/nse-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nEdit `~/.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nse-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/nse-mcp/dist/index.js\"]\n    }\n  }\n}\n```\n\n### Any stdio-based MCP host\n\n```\ncommand: node\nargs:    [\"/absolute/path/to/nse-mcp/dist/index.js\"]\n```\n\n---\n\n## Tool reference\n\n### `get_bulk_deals`\nToday's NSE bulk deals — single-client trades of ≥ 0.5% of a company's listed shares in one session.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `symbol` | string | NSE symbol (e.g. `RELIANCE`). Omit for all. |\n| `dealType` | `BUY` \\| `SELL` \\| `ALL` | Direction filter. Default: `ALL`. |\n\n---\n\n### `get_block_deals`\nToday's NSE block deals — negotiated trades of minimum ₹10 crore executed in the Block Deal Window.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `symbol` | string | NSE symbol. Omit for all. |\n| `dealType` | `BUY` \\| `SELL` \\| `ALL` | Direction filter. Default: `ALL`. |\n\n---\n\n### `get_insider_trading`\nSEBI PIT (Prohibition of Insider Trading) disclosures — promoter and insider buy/sell transactions.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `symbol` | string | NSE symbol. Omit for all companies. |\n| `fromDate` | string | `YYYY-MM-DD`. Default: 30 days ago. |\n| `toDate` | string | `YYYY-MM-DD`. Default: today. |\n\n---\n\n### `get_latest_bulk_deals`\nToday's bulk deals sorted by trade value.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `dealType` | `BUY` \\| `SELL` \\| `ALL` | Direction filter. Default: `ALL`. |\n\n---\n\n### `get_top_bulk_buys`\nLargest bulk-deal purchases today, ranked by total value (quantity × price).\n\n| Parameter | Type | Description |\n|---|---|---|\n| `limit` | number | Results to return. Default: `10`. |\n| `symbol` | string | Restrict to one symbol. |\n\n---\n\n### `get_top_bulk_sells`\nLargest bulk-deal sales today, ranked by total value.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `limit` | number | Results to return. Default: `10`. |\n| `symbol` | string | Restrict to one symbol. |\n\n---\n\n### `get_fii_dii_activity`\nDaily FII and DII net buy/sell figures in the Indian cash market.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `limit` | number | Number of recent trading days. Default: `10`. |\n\n---\n\n### `get_nse_announcements`\nCorporate announcements filed with NSE — board meetings, results, mergers, regulatory updates, etc. (equivalent to SEC 8-K filings).\n\n| Parameter | Type | Description |\n|---|---|---|\n| `symbol` | string | NSE symbol. Omit for all. |\n| `daysBack` | number | Announcements from the last N days. Omit for no date filter. |\n| `limit` | number | Maximum results. Default: `20`. |\n\n---\n\n### `get_market_status`\nCurrent open/closed status of NSE segments (Capital Market, F&O, Currency Derivatives, Commodity) plus live index levels.\n\nNo parameters.\n\n---\n\n### `get_nifty_indices`\nLive data for all NSE indices — price, change, 52-week range, advances/declines count.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `name` | string | Partial, case-insensitive filter. E.g. `\"BANK\"` returns all bank-related indices. |\n\n---\n\n### `get_top_gainers`\nTop gaining stocks by % change in the current session.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `index` | string | NSE index to scan. Default: `NIFTY 500`. |\n| `limit` | number | Results to return. Default: `10`. |\n\n---\n\n### `get_top_losers`\nTop losing stocks by % change in the current session.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `index` | string | NSE index to scan. Default: `NIFTY 500`. |\n| `limit` | number | Results to return. Default: `10`. |\n\n---\n\n### `get_most_active`\nMost actively traded stocks by total traded value (₹) in the current session.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `index` | string | NSE index to scan. Default: `NIFTY 500`. |\n| `limit` | number | Results to return. Default: `10`. |\n\n---\n\n### `search_by_symbol`\nAggregated view for one stock — returns today's bulk deals, block deals, recent insider trades, and recent announcements in a single call.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `symbol` | string | NSE symbol. **Required.** |\n| `daysBack` | number | Look-back window for insider trades and announcements. Default: `30`. |\n\n---\n\n### `get_quote`\nLive 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.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `symbol` | string | NSE symbol (e.g. `RELIANCE`, `TCS`). `.NS` exchange suffix is appended automatically. Pass `SYMBOL.BO` to query BSE instead. **Required.** |\n\n---\n\n### `get_short_selling`\nShort-selling data as reported by brokers to NSE under SEBI's short-selling framework.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `symbol` | string | NSE symbol. Omit for all. |\n| `limit` | number | Return top N stocks by short-sold quantity. |\n\n---\n\n### `get_corporate_actions`\nUpcoming and recent corporate actions — dividends, stock splits, bonus issues, rights issues, buy-backs.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `symbol` | string | NSE symbol. Omit for all companies. |\n| `fromDate` | string | `YYYY-MM-DD`. Default: 3 months ago. |\n| `toDate` | string | `YYYY-MM-DD`. Default: today. |\n\n---\n\n## Example prompts\n\nOnce configured, you can ask your LLM client things like:\n\n- *\"What are today's biggest bulk deals on NSE?\"*\n- *\"Show me insider trades for RELIANCE in the last 30 days.\"*\n- *\"What is the live quote for TCS?\"*\n- *\"Which Nifty 50 stocks are up more than 2% today?\"*\n- *\"What's the FII/DII flow for the last 5 trading days?\"*\n- *\"Give me all corporate actions for INFY this quarter.\"*\n- *\"Show everything you know about HDFC — deals, announcements, insider activity.\"*\n\n---\n\n## Development\n\n```bash\n# Watch mode — recompiles on every save\nnpm run dev\n\n# One-shot build\nnpm run build\n\n# Start the compiled server\nnpm start\n```\n\n### Project structure\n\n```\nsrc/\n├── index.ts          # MCP server entry point — tool list + dispatch\n├── types.ts          # Shared TypeScript interfaces\n├── cache.ts          # In-memory TTL cache\n├── http.ts           # Rate-paced HTTP fetcher with retry\n├── nse/\n│   ├── session.ts    # NSE cookie session management\n│   └── fetch.ts      # NSE API client (wraps http.ts + session)\n├── yahoo/\n│   ├── fetch.ts      # Yahoo Finance HTTP config\n│   ├── parseQuote.ts # Quote JSON parser\n│   └── quoteSummary.ts\n└── tools/            # One file per tool\n    ├── bulkDeals.ts\n    ├── blockDeals.ts\n    ├── insiderTrading.ts\n    ├── latestBulkDeals.ts\n    ├── topBulkBuys.ts\n    ├── topBulkSells.ts\n    ├── fiiDiiActivity.ts\n    ├── announcements.ts\n    ├── marketStatus.ts\n    ├── indices.ts\n    ├── topGainers.ts\n    ├── topLosers.ts\n    ├── mostActive.ts\n    ├── searchBySymbol.ts\n    ├── quote.ts\n    ├── shortSelling.ts\n    └── corporateActions.ts\n```\n\n---\n\n## Data sources\n\n| Data | Source |\n|---|---|\n| Bulk deals, block deals, insider trading, FII/DII, indices, market status, announcements, corporate actions, short selling | NSE India public API (`nseindia.com`) |\n| Live stock quotes | Yahoo Finance (`.NS` suffix for NSE, `.BO` for BSE) |\n\nAll data is fetched in real time. NSE endpoints are cached for 5 minutes; live quotes and market status for 60 seconds.\n\n---\n\n## License\n\nMIT\n"}