devag7/indian-option-mcp

Indian Option MCP Server

Real-time Indian options analytics, strategy building & market intelligence — right inside Claude Desktop.

A Sensibull-replacement that lives inside your AI assistant. Ask Claude to build iron condors, calculate Greeks, scan for unusual OI activity, and more — with live NSE data, available 24/7 (even after market hours).

---

🆓 Free Alternative to Sensibull & Opstra

---

✨ Why Indian Option MCP?

---

🕐 24/7 Availability — Works Even After Market Hours

Most NSE tools and scrapers break after 3:30 PM IST because NSE takes down the option chain API. This MCP server uses a dual-endpoint fallback architecture:

No configuration needed. The fallback is automatic. You always get data, any time of day.

---

🚀 Features

📊 Option Chain Tools

🔢 Greeks & Pricing

🏗️ Strategy Builder — 34 Pre-Built Strategies

📈 Open Interest Analysis

📉 IV Analytics

🌍 Market Data

🛡️ Risk Management

🔍 Scanners

💬 MCP Prompts

---

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

{
  "mcpServers": {
    "indian-options": {
      "command": "node",
      "args": ["/absolute/path/to/Indian-Option-MCP/dist/bundle.mjs"],
      "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:

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

---

🔌 Data Providers

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

---

🏛️ 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.

---

Built with ❤️ for the Indian options trading community

If this project saved you a Sensibull subscription, consider giving it a ⭐