nifty-mcp 0.1.4

MCP server for NIFTY 50 stock and index data — query candles, run backtests, compare strategies. Hosted at https://vjaiswal-nifty-mcp.hf.space/mcp

---

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

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.

---

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

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

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

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

2. Download and start

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:

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

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

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

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

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

Issues and PRs are welcome. Use the bug report template for bugs, feature request for new strategies or datasets.

---

License

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