NSE MCP

An MCP (Model Context Protocol) server that exposes National Stock Exchange of India (NSE) data as MCP tools, powered by the jugaad-data library.

Features

Tools cover every major area of jugaad-data's NSE API:

Area	Tools
Live equity	stock_quote, stock_quote_fno, trade_info, chart_data
Market	market_status, market_turnover, pre_open_market, top_stocks, holiday_list, live_fno, block_deal_session
Indices	all_indices, live_index, index_list, index_df, index_pe_df
Option chains	index_option_chain, equities_option_chain, currency_option_chain, option_chain_contract_info
Corporate	corporate_announcements, symbol_meta, reg_details
History	stock_df, derivatives_df, bhavcopy

Quick install (uv, no venv needed)

For users without Python or venv experience, uv bundles its own standalone CPython and never touches a system Python. The MCP client config then collapses to a single command:

uv tool install nse-mcp

or run on demand without installing:

uvx nse-mcp

While the package is not yet published to PyPI, install straight from this repo:

uv tool install .          # from the repo root
uvx --from . nse-mcp       # on-demand, no install

Bootstrap scripts install uv (if missing), run the tool install, and print the exact config entry to paste into your MCP client:

• Linux / macOS: run ./install.sh from the repo root
• Windows: powershell -ExecutionPolicy ByPass -File install.ps1

Then configure the client with:

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

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the server

python server.py

Runs over stdio; point your MCP client at .venv/bin/python server.py.

Connect an AI client

The server speaks MCP over stdio, so any MCP-compatible desktop app or coding agent can connect to it. The interpreter path differs by OS:

OS	Python path
macOS / Linux	<repo>/.venv/bin/python
Windows	<repo>\.venv\Scripts\python.exe

Replace <repo> with the absolute path to this folder (e.g. /home/you/nse-mcp). Config values must be absolute paths, and the client must be fully restarted after saving the config.

If you installed the server with uv (see Quick install), skip the paths below and use "command": "nse-mcp" with no args instead.

Claude Desktop

1. Open Claude → Settings (the menu in the top bar) → Developer → Edit Config.
2. Add an mcpServers entry to claude_desktop_config.json:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nse-mcp": {
      "command": "/home/you/nse-mcp/.venv/bin/python",
      "args": ["/home/you/nse-mcp/server.py"]
    }
  }
}

3. Quit and relaunch Claude. Click the tools/connectors icon in the composer and select nse-mcp to confirm the tools loaded. Ask e.g. "What is the current NSE market status?" or "Get a live quote for RELIANCE."

ChatGPT (OpenAI)

The ChatGPT desktop app supports local stdio servers. Two ways to add one:

• UI: Settings → MCP servers → Add server → name it nse-mcp, choose STDIO, set the command to <repo>/.venv/bin/python and args to server.py (full path) → Save → Restart.
• Config file: ChatGPT desktop, Codex CLI, and the IDE extension share a TOML config at ~/.codex/config.toml:

[mcp_servers.nse-mcp]
command = "/home/you/nse-mcp/.venv/bin/python"
args = ["/home/you/nse-mcp/server.py"]

ChatGPT on the web (chatgpt.com) connects only to remote MCP servers, so it cannot reach a local stdio server directly; use a desktop client for this server.

Gemini

The Gemini CLI (Google's terminal coding agent) supports local stdio servers. Add the server to ~/.gemini/settings.json (or .gemini/settings.json inside a project):

{
  "mcpServers": {
    "nse-mcp": {
      "command": "/home/you/nse-mcp/.venv/bin/python",
      "args": ["/home/you/nse-mcp/server.py"]
    }
  }
}

Restart the CLI, then run /mcp (or gemini mcp list) to confirm nse-mcp shows as connected. The Gemini web and desktop apps support remote MCP servers only, so use the CLI or the Gemini API (via a coding agent) for this server.

Coding agents

Coding agents accept a project-level .mcp.json (the standard MCP format) or an mcp add command:

Agent	Add command
Claude Code	claude mcp add nse-mcp -- /home/you/nse-mcp/.venv/bin/python /home/you/nse-mcp/server.py
Codex CLI	codex mcp add nse-mcp -- /home/you/nse-mcp/.venv/bin/python /home/you/nse-mcp/server.py
Gemini CLI	gemini mcp add nse-mcp -- /home/you/nse-mcp/.venv/bin/python /home/you/nse-mcp/server.py
Cursor / VS Code	Add the entry below via Settings → MCP (Cursor) or .vscode/mcp.json (VS Code)

Project-level .mcp.json (works with Claude Code, Codex, Cursor, and other clients that read it):

{
  "mcpServers": {
    "nse-mcp": {
      "command": "/home/you/nse-mcp/.venv/bin/python",
      "args": ["/home/you/nse-mcp/server.py"]
    }
  }
}

Troubleshooting

• The server must be started with the venv interpreter (.venv/bin/python), never bare python, so its dependencies are found.
• Paths must be absolute; relative paths fail in most clients.
• If tools don't appear, check JSON/TOML syntax and restart the client completely.
• NSE rate-limits IPs; a transient failure just means retry the same question.

Tests

The suite exercises every NSE functionality against live data, so it needs a stable network connection. NSE rate-limits IPs; tests retry transient blocks.

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

Project structure

nse-mcp/
├── server.py          # FastMCP server: NSE tools, exposes the nse-mcp CLI entry
├── pyproject.toml     # Packaging source of truth (uv/uvx install)
├── install.sh         # Linux/macOS bootstrap installer
├── install.ps1        # Windows bootstrap installer
├── tests/             # Live-data pytest suite
│   ├── helpers.py     # Retry helper, shared fixtures
│   ├── test_historical_stock.py
│   ├── test_index_history.py
│   ├── test_derivatives.py
│   ├── test_archives.py
│   └── test_live.py
├── requirements.txt   # Developer dependency source (venv workflow)
├── AGENTS.md          # Agent operating instructions
└── README.md

Disclaimer

For research and personal use. Data comes from public NSE endpoints; it may be delayed, incomplete, or blocked. Not investment advice.