nifty-mcp 0.1.0

Local MCP server for NIFTY 50 stock and index data — query candles, run backtests, compare strategies.

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.

---

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

{
  "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 → API → Create New Token. Save the downloaded kaggle.json to ~/.kaggle/kaggle.json.

Or export the variables directly:

export KAGGLE_USERNAME="your_username"
export KAGGLE_KEY="your_api_key"

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

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

{
  "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)

{
  "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

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:

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:

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

Or use the bundled script:

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 for the full guide. Once deployed, point your client at:

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

---

Contributing

See CONTRIBUTING.md for how to add new strategy types, datasets, or tools.

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. If you want a new strategy or dataset, use the feature request.

---

License

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