Metadata-Version: 2.4
Name: nse-mcp
Version: 0.1.1
Summary: MCP server exposing NSE market data as AI tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp<2.0,>=1.2.0
Requires-Dist: jugaad-data>=0.35.2
Requires-Dist: pandas>=2.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

# NSE MCP

An MCP (Model Context Protocol) server that turns National Stock Exchange of
India (NSE) data into AI tools. If you use an AI assistant on your computer
(Claude Desktop, Codex, Gemini CLI, Cursor, or similar), this lets that
assistant answer questions about Indian stocks in plain English — *"What's the
live quote for RELIANCE?"*, *"Is the market open right now?"* — with real data
instead of guesses.

MCP is the standard plug that lets AI apps use extra tools: you install the
server once, connect it in the app's settings, and then just ask questions.
Powered by [jugaad-data](https://github.com/jugaad-py/jugaad-data).

## Quick install

Install with one command. No Python or venv needed — the installer bundles its
own runtime and prints the config entry to paste.

**Windows:** open **PowerShell** (search for "PowerShell" in the Start menu),
then run:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/jugaad-py/nse-mcp/main/install.ps1 | iex"
```

**Linux / macOS:** open the **Terminal** app, then run:

```bash
curl -LsSf https://raw.githubusercontent.com/jugaad-py/nse-mcp/main/install.sh | sh
```

You should see a short log ending in `nse-mcp installed.` If Windows asks for
permission, click **Yes**. If something fails, copy the error text and show it
to your AI assistant.

Already have Python or uv? These work too (optional):

```bash
pip install nse-mcp
# or
uv tool install nse-mcp   # on-demand alternative: uvx nse-mcp
```

## Connect your AI app

Your AI app (the "MCP client") reads a small settings file at startup. Add the
block below to that file, save it, then **fully quit and reopen the app**:

```json
{
  "mcpServers": {
    "nse-mcp": {
      "command": "nse-mcp"
    }
  }
}
```

This is the same block the installer prints in the terminal — paste whichever
is easier.

**Finding the settings file:** the folders start with a dot (macOS/Linux) or
are hidden by default (Windows). Fastest way — open the folder directly:

- **Windows:** press `Win + R`, paste `%APPDATA%\Claude`, press Enter
- **macOS:** in Finder choose **Go → Go to Folder…** (Cmd+Shift+G), paste
  `~/Library/Application Support/Claude`, press Enter
- **Linux:** the file is at `~/.codex/config.toml` — open the `~/.codex`
  folder (in your file manager press `Ctrl+H` to show hidden folders)

**If the file already contains text:** don't delete it. If it already has an
`mcpServers` section, add a comma after the last entry, then paste the block
after it.

Where the settings file lives, by app:

| App | Settings file |
| --- | --- |
| Claude Desktop | `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) |
| ChatGPT desktop / Codex CLI | `~/.codex/config.toml`, as `[mcp_servers.nse-mcp]` |
| Gemini CLI | `~/.gemini/settings.json` |
| Claude Code, Cursor, VS Code | `.mcp.json` in the project root, or `mcp add nse-mcp -- nse-mcp` |

ChatGPT on the web connects only to remote servers, so use a desktop app.

## What you can ask

- "Get a live quote for RELIANCE" — price, change, volume, market cap
- "Is the NSE market open right now?"
- "Which stocks gained the most today?"
- "Show me INFY's closing price for the last 6 months"
- "What's NIFTY 50's P/E compared to a year ago?"

## Features

- **Live prices and trades** — current price, the day's high and low, volume,
  buy/sell depth, and futures/options contracts for a symbol (`stock_quote`,
  `stock_quote_fno`, `trade_info`, `chart_data`)
- **Market overview** — open/closed status, total turnover, biggest gainers
  and losers, pre-market prices, trading holidays, F&O securities, and large
  bulk trades (`market_status`, `market_turnover`, `pre_open_market`,
  `top_stocks`, `holiday_list`, `live_fno`, `block_deal_session`)
- **Indices** — live index quotes and which stocks belong to an index
  (`all_indices`, `live_index`, `index_list`)
- **Option chains** — the contracts available for an index, stock, or currency
  pair, with their set prices and dates (`index_option_chain`,
  `equities_option_chain`, `currency_option_chain`,
  `option_chain_contract_info`)
- **Corporate actions** — announcements, symbol metadata, registrar details
  (`corporate_announcements`, `symbol_meta`, `reg_details`)
- **History** — past daily prices for stocks and indices, plus index P/E,
  P/B, and dividend yield (`stock_history`, `index_history`, `index_pe_history`)

Plain-language glossary for the jargon above:

| Term | Meaning |
| --- | --- |
| OHLC | Open, high, low, close — the day's price range |
| F&O | Futures and options — contracts to buy or sell at a set price and date |
| Option chain | All the contracts for a symbol at their set prices (strikes) and dates (expiries) |
| P/E | Price-to-earnings — how expensive a stock is relative to its profits (P/B is the same idea, vs. its book value) |
| Dividend yield | The annual dividend paid, as a percentage of the share price |
| Block deal | A single very large trade, usually between institutions |

## For developers

```bash
git clone https://github.com/jugaad-py/nse-mcp
cd nse-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
```

Run the tests (live NSE data; needs a stable network):

```bash
.venv/bin/python -m pytest tests/ -v
```

Run the server directly:

```bash
.venv/bin/python server.py
```

## Troubleshooting

- Tools don't appear after the config change? Fully quit and reopen the app.
- Check the settings file is valid (quotes and commas in JSON, one `=` per line
  in TOML) and that `nse-mcp` starts without errors when run in a terminal.
- NSE rate-limits IPs. A transient failure just means retry the question.

## Project structure

```
nse-mcp/
├── server.py          # MCP server: NSE tools, exposes the nse-mcp CLI entry
├── pyproject.toml     # Packaging source of truth
├── install.sh         # Linux/macOS one-line installer
├── install.ps1        # Windows one-line installer
├── .github/workflows/ # CI: tests, PyPI publish, version check
├── tests/             # Live-data pytest suite
└── requirements.txt   # Developer dependencies
```

## Disclaimer

For research and personal use. Data comes from public NSE endpoints and may be
delayed or unavailable. Not investment advice.
