Metadata-Version: 2.4
Name: nifty-mcp
Version: 0.1.3
Summary: MCP server for NIFTY 50 stock and index data — query candles, run backtests, compare strategies. Hosted at https://vjaiswal-nifty-mcp.hf.space/mcp
Project-URL: Homepage, https://github.com/vishalmdi/nifty-mcp
Project-URL: Repository, https://github.com/vishalmdi/nifty-mcp
Project-URL: Bug Tracker, https://github.com/vishalmdi/nifty-mcp/issues
Author-email: Vishal Jaiswal <vishal.jaiswal23@gmail.com>
License-Expression: MIT
Keywords: backtesting,finance,india,mcp,nifty,nifty50,stocks,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: duckdb>=1.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: kagglehub>=0.3.0
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pytz>=2024.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

---
title: nifty-mcp
emoji: 📈
colorFrom: blue
colorTo: green
sdk: docker
app_port: 8000
pinned: false
---

# nifty-mcp — Source Repository

> **Looking to connect?** The user-facing landing page is at
> **[github.com/vishalmdi/indian-stocks-mcp](https://github.com/vishalmdi/indian-stocks-mcp)**
>
> Hosted MCP server: `https://vjaiswal-nifty-mcp.hf.space/mcp`

This is the private maintainer repository containing the data pipeline, server source code, HuggingFace Dockerfile, and GitHub Actions for Kaggle sync.

[![PyPI version](https://img.shields.io/pypi/v/nifty-mcp?color=blue)](https://pypi.org/project/nifty-mcp/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/nifty-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Tests](https://img.shields.io/github/actions/workflow/status/vishalmdi/nifty-mcp/test.yml?label=tests)](https://github.com/vishalmdi/nifty-mcp/actions)

---

## Quickstart — paste one URL, done

Add this to your MCP client. No Kaggle account. No installs.

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "nifty": {
      "type": "http",
      "url": "https://vjaiswal-nifty-mcp.hf.space/mcp"
    }
  }
}
```

**VS Code** (`.vscode/mcp.json`), **Cursor** (`.cursor/mcp.json`), and **Claude.ai** (Custom MCP → paste URL) all use the same format.

Then ask Claude anything:

---

## What you can ask

> *"What was RELIANCE's intraday high and low on Union Budget day 2024?"*

> *"Run a 20/50 SMA crossover backtest on NIFTY 50 daily from 2018 to 2024. What's the Sharpe ratio?"*

> *"Compare RSI mean reversion vs EMA crossover on INFY — which had better risk-adjusted returns?"*

> *"Which NIFTY 100 stocks crossed above their 20-day high in the last 30 trading sessions?"*

> *"Show me Bank NIFTY's 15-minute candles during the March 2020 crash"*

> *"Backtest a Supertrend strategy on NIFTY IT with a 2% stop loss. What was the max drawdown?"*

> *"Compare 5 different SMA window combinations on NIFTY 50 and rank them by profit factor"*

> *"Run a MACD crossover backtest on RELIANCE from 2020 to 2024. Compare it against Bollinger Bands on the same data."*

> *"Use Stochastic oscillator strategy on BANK NIFTY 15-minute data with a 2% stop loss"*

> *"What's the average intraday range (high minus low) for HDFC BANK on 1-minute data in January 2024?"*

> *"Show me the latest day's 1-minute candles for NIFTY 50"*

Claude calls the right tools automatically. You get real numbers, real trades, real equity curves — not hallucinations.

---

## What's under the hood

### 7 MCP tools

| Tool | What Claude can do |
|------|--------------------|
| `dataset_status` | Check data coverage: 187M+ rows, latest available date, row counts per dataset |
| `list_symbols` | Browse all 253 symbols with their available intervals and date coverage |
| `get_candles` | Fetch raw OHLCV data — any symbol, any interval, any date range (up to 10k rows). Use `desc=True` to get the latest N candles without needing to know the date |
| `run_backtest` | Run a strategy config: get P&L, Sharpe, max drawdown, win rate, every trade, and the full equity curve |
| `compare_strategies` | Run up to 10 configs side-by-side and rank them by any metric |
| `get_backtest_report` | Retrieve any saved backtest by `run_id`, or list recent runs |
| `help` | List all available tools with descriptions, parameters, and usage examples |

### Data coverage

| Dataset | Symbols | Intervals | History |
|---------|---------|-----------|---------|
| Indices | 136 (NIFTY 50, Bank NIFTY, NIFTY IT, NIFTY Pharma, NIFTY Auto, INDIA VIX, sector indices...) | 1m, 5m, 15m, 60m, day | 6+ years |
| Stocks | 117 NIFTY 100 constituents (RELIANCE, TCS, INFY, HDFC, ICICI, WIPRO, BAJFINANCE...) | 1m | 6+ years |

All data is stored in a single DuckDB table partitioned by dataset. Every timestamp is in `Asia/Kolkata` (+05:30).

### 8 backtest strategy types

| Type | What it does | Parameters |
|------|-------------|------------|
| `sma_crossover` | Buy when fast SMA crosses above slow SMA | `fast_window`, `slow_window` |
| `ema_crossover` | Same with exponential moving averages | `fast_window`, `slow_window` |
| `rsi_mean_reversion` | Buy oversold, sell overbought | `rsi_window` (14), `oversold` (30), `overbought` (70) |
| `breakout` | Buy on N-day high breakout | `lookback_window` |
| `supertrend` | ATR-based trend-following | `atr_window` (10), `multiplier` (3.0) |
| `macd_crossover` | Buy when MACD line crosses above signal line | `fast_window` (12), `slow_window` (26), `macd_signal` (9) |
| `bollinger_bands` | Buy at lower band, sell at upper band | `bb_window` (20), `num_std` (2.0) |
| `stochastic` | Buy oversold %K/%D, sell overbought | `stoch_window` (14), `stoch_signal` (3), `oversold` (20), `overbought` (80) |

Every strategy supports optional exit rules:

```json
{
  "stop_loss_pct": 0.02,
  "take_profit_pct": 0.05,
  "trailing_stop_pct": 0.03
}
```

### Metrics returned by every backtest

`total_return_pct`, `annualized_return_pct`, `sharpe_ratio`, `max_drawdown_pct`, `win_rate`, `total_trades`, `profit_factor` — plus a full `trades` list and `equity_curve`.

---

## Backtest config example

Tell Claude to run this, or use the CLI directly:

```json
{
  "name": "NIFTY 50 SMA crossover",
  "dataset": "index",
  "symbol": "NIFTY 50",
  "interval": "day",
  "start": "2019-01-01",
  "end": "2024-12-31",
  "initial_cash": 100000,
  "strategy": {
    "type": "sma_crossover",
    "fast_window": 20,
    "slow_window": 50
  },
  "position_sizing": {
    "type": "fractional",
    "fraction": 1.0
  },
  "costs": {
    "brokerage_per_order": 20,
    "stt_sell_pct": 0.001,
    "slippage_pct": 0.0005
  }
}
```

---

## Run your own copy

Don't want to use the hosted version? You can run your own MCP server locally or deploy it yourself.

### Local setup

**1. Get a Kaggle API key (free)**

Go to [kaggle.com/settings](https://www.kaggle.com/settings) → API → **Create New Token**. Save `kaggle.json` to `~/.kaggle/kaggle.json`.

**2. Download and start**

```bash
pip install nifty-mcp
nifty-mcp sync --dataset all      # ~5 min, downloads ~500 MB
nifty-mcp serve                   # stdio MCP server (for Claude Desktop)
```

Add to Claude Desktop with:
```json
{
  "mcpServers": {
    "nifty": {
      "command": "uvx",
      "args": ["nifty-mcp", "serve"],
      "env": { "NIFTY_MCP_DATA_DIR": "~/.nifty-mcp/data" }
    }
  }
}
```

**3. Keep data fresh (incremental updates)**

Run weekly via cron — only appends rows newer than what's already in the DB:

```cron
30 3 * * 0 KAGGLE_USERNAME=... KAGGLE_KEY=... nifty-mcp sync --dataset all --incremental >> ~/.nifty-mcp/sync.log 2>&1
```

Or use the bundled script:
```bash
bash scripts/refresh_datasets.sh
```

The `--incremental` flag queries the max date per symbol and only loads rows from dates strictly after it. Safe to run repeatedly.

### Self-hosted deployment (free)

Deploy your own hosted instance at $0/month:
- **GitHub Actions** syncs from Kaggle every Monday and Thursday
- **Cloudflare R2** stores the DuckDB file (10 GB free)
- **HuggingFace Spaces** serves the MCP endpoint

See [**SELF_HOST.md**](SELF_HOST.md) for the full guide.

---

## CLI Reference

```
nifty-mcp sync     [--dataset index|stocks|all] [--force] [--incremental]
nifty-mcp normalize --raw-dir /path/to/csvs [--dataset stocks] [--incremental]
nifty-mcp status   [--dataset index|stocks|all]
nifty-mcp backtest --config strategy.json
nifty-mcp download --url <url> [--force]
nifty-mcp serve    [--transport stdio|sse]
```

Override the data directory at any time:
```bash
NIFTY_MCP_DATA_DIR=/my/path nifty-mcp sync
```

### Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `NIFTY_MCP_DATA_DIR` | `~/.nifty-mcp/data` | Local data directory |
| `NIFTY_MCP_REMOTE_DB_URL` | — | Read from a remote DuckDB over HTTP (no local file needed) |

---

## Contributing

```bash
git clone https://github.com/vishalmdi/nifty-mcp
cd nifty-mcp
pip install -e ".[dev]"
pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add strategy types, datasets, or tools.

Issues and PRs are welcome. Use the [bug report template](https://github.com/vishalmdi/nifty-mcp/issues/new?template=bug_report.md) for bugs, [feature request](https://github.com/vishalmdi/nifty-mcp/issues/new?template=feature_request.md) for new strategies or datasets.

---

## License

MIT. Data sourced from Kaggle datasets published under their respective licenses.
