Metadata-Version: 2.4
Name: nse-mcp
Version: 0.1.0
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.1
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 exposes National Stock Exchange of
India (NSE) data as MCP tools, powered by the
[jugaad-data](https://github.com/jugaad-py/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](https://docs.astral.sh/uv/)
bundles its own standalone CPython and never touches a system Python. The MCP
client config then collapses to a single command:

```bash
uv tool install nse-mcp
```

or run on demand without installing:

```bash
uvx nse-mcp
```

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

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

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

## Setup

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

## Run the server

```bash
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](#quick-install-uv-no-venv-needed)),
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`

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

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

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

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

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