indian-option-mcp

<p align="center"> <img src="https://img.shields.io/badge/🇮🇳_Indian_Options-MCP_Server-orange?style=for-the-badge&labelColor=1a1a2e" alt="Indian Option MCP" /> </p>

<h1 align="center">Indian Option MCP Server</h1>

<p align="center"> <strong>Real-time Indian options analytics, strategy building & market intelligence — right inside Claude Desktop.</strong> </p>

<p align="center"> <a href="https://github.com/devag7/Indian-Option-MCP/stargazers"><img src="https://img.shields.io/github/stars/devag7/Indian-Option-MCP?style=flat-square&color=FFD700" alt="Stars" /></a> <a href="https://www.npmjs.com/package/indian-option-mcp"><img src="https://img.shields.io/npm/v/indian-option-mcp?style=flat-square&color=CB3837" alt="npm" /></a> <a href="https://www.npmjs.com/package/indian-option-mcp"><img src="https://img.shields.io/npm/dm/indian-option-mcp?style=flat-square&color=blue" alt="Downloads" /></a> <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /> <img src="https://img.shields.io/badge/Node.js_20+-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js" /> <img src="https://img.shields.io/badge/MCP_SDK-Claude_Desktop-8B5CF6?style=flat-square" alt="MCP" /> <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" /> <img src="https://img.shields.io/badge/data-NSE_India-blue?style=flat-square" alt="NSE" /> <img src="https://img.shields.io/badge/strategies-34+-ff6b6b?style=flat-square" alt="Strategies" /> <img src="https://img.shields.io/badge/tools-27+-ffd93d?style=flat-square" alt="Tools" /> <img src="https://img.shields.io/badge/zero_external-trading_deps-2d3436?style=flat-square" alt="No external deps" /> </p>

<p align="center"> <em>A Sensibull-replacement that lives inside your AI assistant. Ask Claude to build iron condors, calculate Greeks, scan for unusual OI activity, and more — all with live NSE data.</em> </p>

---

🆓 Free Alternative to Sensibull & Opstra

Feature	Sensibull (₹1500/mo)	Opstra (₹999/mo)	Indian Option MCP (Free)
Option Chain	✅	✅	✅ Live from NSE
Strategy Builder	✅ (20+)	✅ (15+)	✅ 34 strategies
Greeks Calculator	✅	✅	✅ Black-Scholes
Max Pain	✅	✅	✅
OI Analysis	✅	✅	✅
IV Smile/Skew	❌	✅	✅
Position Sizing	❌	❌	✅
Margin Estimation	❌	❌	✅
Probability of Profit	❌	❌	✅
AI-Powered Analysis	❌	❌	✅ Claude AI
Natural Language	❌	❌	✅ "Build me an Iron Condor"
API/Programmatic	❌	❌	✅ MCP Protocol
Price	₹1500/month	₹999/month	🆓 Forever Free

---

✨ Why Indian Option MCP?

Pain Point	Old Way	With This MCP
Checking option chains	Open Sensibull/NSE website, scroll, compare	"Show me NIFTY option chain"
Building strategies	Manually pick strikes, calculate P&L	"Build an iron condor on BANKNIFTY"
Greeks analysis	Open Black-Scholes calculator, enter values	"What are the Greeks for NIFTY 24000 CE?"
Finding support/resistance from OI	Stare at OI columns, do mental math	"Where is the highest OI in NIFTY?"
Position sizing	Spreadsheet + guesswork	"Size a position for ₹5L capital, 2% risk"

---

🚀 Features

📊 Option Chain Tools

Tool	Description
get_option_chain	Full option chain with strikes, LTP, OI, IV, volume, bid/ask for calls & puts
get_expiry_dates	All available expiry dates for any F&O symbol
get_spot_price	Current spot/underlying price of any stock or index

🔢 Greeks & Pricing

Tool	Description
calculate_greeks	All Greeks — Delta, Gamma, Theta, Vega, Rho — via Black-Scholes
calculate_iv	Implied Volatility from market price (Newton-Raphson method)
calculate_option_price	Theoretical option price using Black-Scholes model
what_if_greeks	Scenario analysis — how Greeks change under hypothetical conditions

🏗️ Strategy Builder — 34 Pre-Built Strategies

Tool	Description
build_strategy	Build any of 34 strategies with real market prices, payoff & breakevens
custom_strategy	Build custom multi-leg strategies with specific strikes
suggest_strategy	Get strategy suggestions based on outlook & risk preference
list_strategies	Browse all available strategies by category
calculate_payoff	Payoff/P&L table at expiry across price scenarios

📈 Open Interest Analysis

Tool	Description
calculate_max_pain	Max Pain strike — where option buyers lose the most
get_pcr	Put-Call Ratio (OI, Volume, and Change based) with interpretation
highest_oi_strikes	OI-based support & resistance levels
oi_change_analysis	Change in OI patterns — emerging support/resistance

📉 IV Analytics

Tool	Description
iv_smile	IV Smile curve + IV Skew across strikes
expected_move	Expected price range by expiry (1σ, 1.645σ, 1.96σ)

🌍 Market Data

Tool	Description
market_overview	NIFTY & BANKNIFTY snapshot — spot, ATM IV, PCR, lot size
market_status	Is the NSE market currently open or closed?
lot_size	Lot size for any F&O instrument
next_expiry	Next weekly/monthly expiry date

🛡️ Risk Management

Tool	Description
estimate_margin	SPAN + Exposure margin estimate for option strategies
probability_of_profit	POP calculation using log-normal distribution
position_sizing	Optimal lot count based on capital & risk tolerance

🔍 Scanners

Tool	Description
scan_high_oi	Find strikes with highest institutional OI buildup
unusual_activity	Detect abnormally high volume/OI ratio

💬 MCP Prompts

Prompt	Description
strategy_advisor	Full strategy recommendation workflow — chains, PCR, max pain, expected move, build & size
market_analysis	Comprehensive analysis — OI, PCR, IV smile, max pain, expected move synthesized

---

⚡ Quick Start

Option 1: npx (Recommended — Zero Install)

Add this to your Claude Desktop config:

{
  "mcpServers": {
    "indian-options": {
      "command": "npx",
      "args": ["-y", "indian-option-mcp"]
    }
  }
}

Restart Claude Desktop. Done. 🎉

Option 2: Clone & Build

# Clone the repository
git clone https://github.com/devag7/Indian-Option-MCP.git
cd Indian-Option-MCP

# Install dependencies & build
npm install
npm run build

Configure Claude Desktop

Add this to your Claude Desktop config file:

<details> <summary><strong>📍 Config file locations</strong></summary>

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

</details>

{
  "mcpServers": {
    "indian-options": {
      "command": "node",
      "args": ["/absolute/path/to/Indian-Option-MCP/dist/index.js"],
      "env": {
        "DATA_PROVIDER": "nse"
      }
    }
  }
}

That's it. Restart Claude Desktop and start asking about Indian options! 🎉

---

💬 Example Conversations

Once configured, just talk naturally to Claude:

You: Show me the NIFTY option chain for the nearest expiry

You: Build an iron condor on BANKNIFTY with 3 strikes OTM

You: What's the max pain for NIFTY? Where is OI-based support?

You: I'm bullish on RELIANCE. Suggest a strategy with low risk.

You: Calculate Greeks for NIFTY 24500 CE, 10 days to expiry, 14% IV

You: Show the expected move for NIFTY at 95% confidence

You: Size a short straddle on BANKNIFTY for ₹10L capital, max 2% risk

---

🏗️ Strategy Library

All 34 pre-built strategies, ready to deploy with live market prices:

<table> <tr> <td>

📈 Bullish

Strategy	Legs
long_call	1
bull_call_spread	2
bull_put_spread	2
put_credit_spread	2
synthetic_long	2
covered_call	2
collar	3
strap	2
jade_lizard	3

</td> <td>

📉 Bearish

Strategy	Legs
long_put	1
bear_put_spread	2
bear_call_spread	2
put_debit_spread	2
call_credit_spread	2
synthetic_short	2
protective_put	2
strip	2

</td> </tr> <tr> <td>

⚖️ Neutral

Strategy	Legs
short_straddle	2
short_strangle	2
iron_condor	4
iron_butterfly	4
butterfly	3
calendar_spread	2
double_diagonal	4

</td> <td>

🌊 Volatility

Strategy	Legs
long_straddle	2
long_strangle	2
back_spread_call	2
back_spread_put	2
ratio_call_spread	2
ratio_put_spread	2
short_call	1
short_put	1
broken_wing_butterfly	3
christmas_tree	3

</td> </tr> </table>

💡 Tip: Use list_strategies to browse by category, or suggest_strategy to get recommendations based on your market view.

---

🔌 Data Providers

Provider	API Key	Features	Speed
NSE India (default)	❌ Not needed	Full option chains, OI, IV, volume, spot prices	⚡ Fast
Zerodha Kite (optional)	✅ Required	Full option chains, tick-level data, order book depth	⚡⚡ Faster

NSE (Default — Zero Config)

Works out of the box. The server fetches data directly from NSE India's public endpoints.

# No configuration needed — just build and run
DATA_PROVIDER=nse  # this is the default

Zerodha Kite (Optional)

For traders with a Zerodha account who want faster data and deeper order book:

DATA_PROVIDER=zerodha
KITE_API_KEY=your_api_key
KITE_API_SECRET=your_api_secret
KITE_ACCESS_TOKEN=your_access_token  # refreshed daily

Get credentials from developers.kite.trade

---

⚙️ Environment Variables

Copy .env.example to .env and configure as needed:

cp .env.example .env

Variable	Default	Description
DATA_PROVIDER	nse	Data source — nse (free) or zerodha (needs API key)
KITE_API_KEY	—	Zerodha Kite API key (only if zerodha)
KITE_API_SECRET	—	Zerodha Kite API secret (only if zerodha)
KITE_ACCESS_TOKEN	—	Zerodha session token, refreshed daily (only if zerodha)
CACHE_TTL_SECONDS	5	Real-time data cache lifetime in seconds
INSTRUMENT_CACHE_TTL_HOURS	12	Instrument master cache lifetime in hours
RISK_FREE_RATE	0.07	Annual risk-free rate for Black-Scholes (7% = Indian 10Y bond)
LOG_LEVEL	info	Logging verbosity — debug, info, warn, error

---

🏛️ Architecture

indian-option-mcp/
├── src/
│   ├── index.ts                    # Entry point — stdio transport
│   ├── server.ts                   # MCP server — all 35+ tools registered here
│   ├── config.ts                   # Zod-validated env configuration
│   │
│   ├── data/
│   │   ├── providers/
│   │   │   ├── base.provider.ts    # Abstract data provider interface
│   │   │   ├── nse.provider.ts     # NSE India scraper (default)
│   │   │   └── zerodha.provider.ts # Kite Connect API client
│   │   ├── provider-factory.ts     # Provider factory pattern
│   │   ├── cache/
│   │   │   ├── memory-cache.ts     # TTL-based in-memory cache
│   │   │   └── instrument-cache.ts # Long-lived instrument master cache
│   │   ├── constants/
│   │   │   ├── lot-sizes.ts        # F&O lot sizes (NIFTY=75, BANKNIFTY=30, etc.)
│   │   │   ├── expiry-calendar.ts  # Expiry date calculations
│   │   │   └── indices.ts          # Index metadata & strike intervals
│   │   └── models/
│   │       ├── option-chain.ts     # Option chain data models
│   │       ├── instrument.ts       # Instrument definitions
│   │       ├── quote.ts            # Quote/tick models
│   │       ├── strategy.ts         # Strategy type definitions
│   │       └── index.ts            # Model barrel exports
│   │
│   ├── engine/
│   │   ├── black-scholes.ts        # Option pricing & Greeks (Δ, Γ, Θ, ν, ρ)
│   │   ├── implied-volatility.ts   # IV solver (Newton-Raphson)
│   │   ├── iv-surface.ts           # IV Smile, Skew, Rank, Percentile, HV
│   │   ├── strategy-builder.ts     # 34 strategy templates + builder
│   │   ├── payoff.ts               # Payoff/P&L at expiry engine
│   │   ├── max-pain.ts             # Max Pain calculator
│   │   ├── pcr.ts                  # Put-Call Ratio analyzer
│   │   ├── oi-analysis.ts          # OI distribution & activity detection
│   │   ├── margin-calculator.ts    # SPAN margin estimator
│   │   └── risk-metrics.ts         # POP, Kelly, position sizing
│   │
│   └── utils/
│       ├── date.ts                 # Market hours, DTE, expiry helpers
│       ├── format.ts               # Currency, number, OI formatting
│       ├── math.ts                 # Normal CDF, statistical functions
│       └── logger.ts               # Stderr-only logger (MCP-safe)
│
├── dist/                           # Compiled output
├── package.json
├── tsconfig.json
└── .env.example

Design Principles

• Zero external trading dependencies — only @modelcontextprotocol/sdk and zod
• Provider pattern — swap between NSE and Zerodha with one env variable
• Pure computation engine — all pricing, Greeks, and analytics are self-contained
• MCP-safe logging — all output goes to stderr, never stdout (protects stdio transport)
• Startup validation — Zod schemas validate all config at boot, not at runtime

---

🛠️ Development

# Watch mode (recompile on save)
npm run dev

# Type-check without emitting
npm run lint

# Run tests
npm test

# Inspect with MCP Inspector
npm run inspect

# Clean build artifacts
npm run clean

---

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch — git checkout -b feat/my-feature
3. Commit your changes — git commit -m "feat: add my feature"
4. Push to your branch — git push origin feat/my-feature
5. Open a Pull Request

Areas for Contribution

• 🆕 New strategies (e.g., seagull, condor variations)
• 🌐 Additional data providers (Upstox, Angel One, etc.)
• 📊 Enhanced analytics (IV term structure, correlation analysis)
• 🧪 Test coverage for engine modules
• 📚 Documentation improvements

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

<p align="center"> <strong>Built with ❤️ for the Indian options trading community</strong> <br /> _{If this project saved you a Sensibull subscription, consider giving it a ⭐} </p>