# NSE MCP

An [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.

Modelled after [OpenInsider-MCP](https://github.com/btopn/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

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

### 2. Install dependencies

```bash
npm install
```

### 3. Build

```bash
npm run build
```

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

### 4. Verify it starts

```bash
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**
```bash
export NSE_MCP_UA="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/121.0.0.0 Safari/537.36"
```

**Windows (PowerShell)**
```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):

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

With an env override:

```json
{
  "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:

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

### Cursor

Edit `~/.cursor/mcp.json`:

```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

```bash
# 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