Metadata-Version: 2.4
Name: nifty-mcp
Version: 0.1.0
Summary: Local MCP server for NIFTY 50 stock and index data — query candles, run backtests, compare strategies.
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
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# nifty-mcp

**Ask Claude about Indian stocks. Get real answers.**

`nifty-mcp` is a local MCP server that gives Claude (and any MCP client) direct access to NIFTY 50 historical data — OHLCV candles, symbol lists, and a full backtesting engine. No API keys, no subscriptions. Data lives on your machine.

[![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)

---

## What you can do

Once installed, just ask Claude:

> *"What was RELIANCE's price trend in January 2024?"*
> *"Run a 20/50 SMA crossover backtest on NIFTY 50 for the last 5 years"*
> *"Compare RSI mean reversion vs EMA crossover on INFY — which had better Sharpe?"*
> *"Show me all symbols available in the 15-minute interval"*

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

---

## Quick Start

### 1. Add to your MCP client

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

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

**VS Code** (`.vscode/mcp.json`) and **Cursor** (`.cursor/mcp.json`) use the same format.

### 2. Get a Kaggle API key (one-time, free)

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

Or export the variables directly:
```bash
export KAGGLE_USERNAME="your_username"
export KAGGLE_KEY="your_api_key"
```

### 3. Download data (one-time, ~5 min)

```bash
pip install nifty-mcp
nifty-mcp sync --dataset all
```

This downloads ~500 MB of CSV data from Kaggle and normalizes it into a local DuckDB at `~/.nifty-mcp/data/nifty.duckdb`. After this, `uvx nifty-mcp serve` starts in under a second — no credentials needed.

---

## Available Tools

| Tool | What Claude can do with it |
|------|---------------------------|
| `dataset_status` | Check sync status, row counts, date coverage |
| `list_symbols` | See all symbols with date ranges; filter by interval or dataset |
| `get_candles` | Fetch OHLCV data for any symbol (up to 10,000 rows per call) |
| `run_backtest` | Run a strategy and get metrics, trades, equity curve |
| `compare_strategies` | Run up to 10 configs side-by-side and rank them |
| `get_backtest_report` | Retrieve a saved backtest by `run_id` or list recent runs |

---

## Datasets

Two free Kaggle datasets, pre-normalized into a single DuckDB table:

| ID | Source | Symbols | Intervals |
|----|--------|---------|-----------|
| `index` | `debashis74017/nifty-50-minute-data` | 136 indices (NIFTY 50, Bank NIFTY, sector indices…) | 1m, 3m, 5m, 15m, day |
| `stocks` | `debashis74017/stock-market-data-nifty-50-stocks-1-min-data` | 117 NIFTY 100 stocks | 1m |

Both live in the same `candles` table, partitioned by `dataset_id`. The sync is idempotent — re-running it only re-downloads if Kaggle published new files.

---

## Backtesting

### Strategy config

```json
{
  "name": "NIFTY SMA crossover",
  "dataset": "index",
  "symbol": "NIFTY 50",
  "interval": "day",
  "start": "2020-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
  }
}
```

### Strategy types

| Type | Required params | Optional params |
|------|----------------|-----------------|
| `sma_crossover` | `fast_window`, `slow_window` | — |
| `ema_crossover` | `fast_window`, `slow_window` | — |
| `rsi_mean_reversion` | — | `rsi_window` (14), `oversold` (30), `overbought` (70) |
| `breakout` | `lookback_window` | — |
| `supertrend` | — | `atr_window` (10), `multiplier` (3.0) |

### Exit rules (add to any strategy)

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

### Metrics returned

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

### Run from CLI

```bash
nifty-mcp backtest --config strategy.json
```

---

## CLI Reference

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

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

---

## Weekly Data Refresh

The sync command is idempotent. Run it weekly via cron to stay current:

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

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

---

## Hosted / Zero-Setup Version

Don't want to deal with Kaggle credentials or local storage? Deploy your own hosted version:

- **GitHub Actions** syncs Kaggle data every Sunday (free 2000 min/month)
- **Cloudflare R2** stores the DuckDB file (free 10 GB, 10M reads/month)
- **Fly.io** serves the MCP via SSE (free tier: 3 shared VMs)

**Cost: $0/month** within free tier limits.

See [**DEPLOY.md**](DEPLOY.md) for the full guide. Once deployed, point your client at:

```json
{
  "mcpServers": {
    "nifty-hosted": {
      "type": "sse",
      "url": "https://your-app.fly.dev/sse"
    }
  }
}
```

---

## Contributing

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

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

Issues and PRs are welcome. If you find a bug, use the [bug report template](https://github.com/vishalmdi/nifty-mcp/issues/new?template=bug_report.md). If you want a new strategy or dataset, use the [feature request](https://github.com/vishalmdi/nifty-mcp/issues/new?template=feature_request.md).

---

## License

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