groww-mcp

# Groww MCP Server [](https://www.ruby-lang.org/) [](https://modelcontextprotocol.io/) [](LICENSE) [](https://groww.in/trade-api) > **The most complete MCP server for Groww** — 25 tools, automated TOTP auth, smart orders (GTT/OCO), option chain with Greeks, and backtesting. No other Groww MCP has all of these. A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects AI assistants (Claude, GPT, Gemini) to the [Groww](https://groww.in/) trading platform. Trade stocks, manage your portfolio, place F&O orders, and access live market data — all through natural language. Built with Ruby, powered by the official [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk). ### Key Highlights - **25 tools** — most comprehensive Groww MCP available - **Zero manual auth** — automated TOTP token generation (no daily website visits) - **Smart Orders** — GTT and OCO support (only Groww MCP with this) - **Option Chain** — with Greeks (Δ, Γ, Θ, ν) for options analysis - **Works with** — Claude Code, Claude Desktop, any MCP-compatible AI assistant ## Why This MCP? | Feature | groww-mcp (this) | [darved2305](https://github.com/darved2305/groww-mcp) (TS) | [arkapravasinha](https://github.com/arkapravasinha/groww-mcp-server) (Python) | [karthik1729](https://github.com/karthik1729/groww-mcp) (Go) | |---------|:-:|:-:|:-:|:-:| | **Tools** | **25** | 23 (many broken) | ~20 | 15 | | **Auto TOTP auth** | ✅ | ❌ | ❌ | ❌ | | **Token auto-refresh** | ✅ | ❌ | ❌ | ❌ | | **3 auth methods** | ✅ | Token only | API Key only | Token only | | **Smart Orders (GTT/OCO)** | ✅ | ❌ | ❌ | ❌ | | **Option Chain + Greeks** | ✅ | ❌ | ❌ | ❌ | | **Instruments Search** | ✅ | ❌ | ✅ | ❌ | | **Backtesting** | ✅ | ❌ | ❌ | ❌ | | **Correct API paths** | ✅ | ❌ | ✅ | ✅ | | **F&O support** | ✅ | ❌ | ✅ | ✅ | | **Subscription hints** | ✅ | ❌ | ❌ | ❌ | | **Official MCP SDK** | ✅ | ✅ | ✅ | Custom | | **Language** | Ruby | TypeScript | Python | Go | ## Quick Start ### Prerequisites - Ruby >= 3.1.0 (tested on 4.0.1) - A [Groww](https://groww.in/) trading account with API access ### Installation ```bash git clone https://github.com/developerjai/groww-mcp.git cd groww-mcp bundle install ``` ### Configuration ```bash cp .env.example .env ``` Edit `.env` with your Groww credentials (see [Authentication](#authentication) below). ### Connect to Claude Code Add to your `.mcp.json`: ```json { "mcpServers": { "groww": { "type": "stdio", "command": "ruby", "args": ["/path/to/groww-mcp/bin/groww-mcp"], "env": { "GROWW_TOTP_KEY": "your_totp_key", "GROWW_TOTP_SECRET": "your_totp_secret" } } } } ``` Or use with **Claude Desktop** — add to `claude_desktop_config.json`: ```json { "mcpServers": { "groww": { "command": "ruby", "args": ["/path/to/groww-mcp/bin/groww-mcp"] } } } ``` ## Authentication Groww MCP supports **3 authentication methods**. Choose the one that fits your workflow: ### Method 1: TOTP (Recommended) **Fully automated.** No daily manual steps. The server generates access tokens automatically using a TOTP secret. #### Setup (one-time, 2 minutes): 1. Go to [groww.in](https://groww.in/) → Log in 2. Navigate to **Profile** → **Settings** → **Trading APIs** 3. Click **"Generate API key"** dropdown → **"Generate TOTP token"** 4. You'll get two values: - **TOTP Token** (a long JWT string starting with `eyJ...`) → This is your `GROWW_TOTP_KEY` - **TOTP QR Secret** (a short base32 string like `UG3X...`) → This is your `GROWW_TOTP_SECRET` 5. Add to your `.env`: ```bash GROWW_TOTP_KEY=eyJraWQi...your_totp_jwt_key GROWW_TOTP_SECRET=UG3XTATB22XLH5SGGLHHV736PEOYUZSB ``` That's it. The server will automatically generate fresh access tokens on every startup. No manual steps, no daily website visits. ### Method 2: API Key + Secret (Approval) Requires **daily approval** on the Groww website before the server can generate tokens. #### Setup: 1. Go to [groww.in](https://groww.in/) → **Settings** → **Trading APIs** 2. Click **"Generate API key"** → Create a key 3. Copy the API Key and API Secret 4. Add to `.env`: ```bash GROWW_API_KEY=eyJraWQi...your_api_key GROWW_API_SECRET=your_api_secret ``` 5. **Daily**: Visit the Trading APIs page and click "Approve" next to your key ### Method 3: Direct Access Token (Manual) For quick testing. Token expires daily at **6:00 AM IST**. 1. Go to [groww.in](https://groww.in/) → **Settings** → **Trading APIs** 2. Click **"Generate API key"** dropdown → **"Generate Access Token"** 3. Copy the token 4. Add to `.env`: ```bash GROWW_ACCESS_TOKEN=eyJraWQi...your_access_token ``` > ⚠️ You'll need to regenerate this token every day before 6:00 AM IST. ## Tools ### Portfolio (Free) | Tool | Description | |------|-------------| | `get_holdings` | All stocks in your DEMAT account with avg price, quantity, ISIN | | `get_positions` | Open intraday/F&O positions with unrealized P&L | | `get_margins` | Available cash, collateral, equity & F&O margin details | | `calculate_margin` | Pre-check margin requirement before placing orders | ### Orders (Free) | Tool | Description | |------|-------------| | `get_orders` | List all orders with status, filterable by segment | | `get_order_detail` | Detailed status of a specific order | | `get_order_trades` | Partial fill details for a specific order | | `place_order` | Place BUY/SELL orders (MARKET, LIMIT, SL, SL-M) | | `modify_order` | Modify pending orders (price, quantity, type) | | `cancel_order` | Cancel open/pending orders | ### Smart Orders — GTT/OCO (Free) | Tool | Description | |------|-------------| | `get_smart_orders` | List all GTT and OCO orders | | `create_smart_order` | Create GTT (trigger-based) or OCO (stop-loss + target) | | `modify_smart_order` | Update triggers, quantities, and prices | | `cancel_smart_order` | Cancel pending smart orders | > **GTT** (Good Till Triggered): Automatically places an order when price hits your target. > **OCO** (One Cancels Other): Sets both stop-loss AND target — whichever hits first executes. ### Market Data (₹499/mo subscription) | Tool | Description | |------|-------------| | `get_quote` | Live quote with OHLC, bid/ask, volume, change % | | `get_ltp` | Last traded price for up to 50 symbols at once | | `get_ohlc` | OHLC data for up to 50 symbols | | `get_option_chain` | Full option chain with OI, IV, and Greeks (Δ, Γ, Θ, ν) | | `get_historical_data` | Historical candlestick data for analysis | > Market data tools require the [Groww Live Data subscription](https://groww.in/trade-api) (₹499 + GST/month). Without it, these tools will return a clear error message explaining how to subscribe. ### Instruments (Free) | Tool | Description | |------|-------------| | `search_instruments` | Find stocks, F&O, ETFs by name or symbol | | `get_instrument_detail` | Lot size, tick size, expiry, contract details | | `download_instruments` | Complete CSV of all tradable instruments | ### Backtesting (₹499/mo subscription) | Tool | Description | |------|-------------| | `run_backtest` | Simulate a trading strategy on historical data | ### Other | Tool | Description | |------|-------------| | `authenticate` | Manually trigger token refresh (auto-handled normally) | | `get_profile` | Account info: UCC, exchanges, segments, DDPI status | ## Groww API Rate Limits | Category | Requests/sec | Requests/min | |----------|:---:|:---:| | Orders (create, modify, cancel) | 10 | 250 | | Live Data (quote, LTP, OHLC) | 10 | 300 | | Non-Trading (orders, holdings, positions) | 20 | 500 | ## Examples Once connected, you can use natural language with your AI assistant: ``` "Show me my current holdings" "What's my available margin?" "Place a limit buy order for 10 shares of RELIANCE at ₹2,800" "Cancel order ORD123456" "Get the current price of INFY" (requires Live Data subscription) ``` ## Project Structure ``` groww-mcp/ ├── bin/ │ └── groww-mcp # Executable entry point ├── lib/ │ ├── groww_mcp.rb # Main module, tool registry (25 tools) │ └── groww_mcp/ │ ├── version.rb # Gem version │ ├── auth.rb # 3-method authentication (TOTP, approval, manual) │ ├── client.rb # Groww API client (net/http, correct endpoints) │ ├── base_tool.rb # Shared tool helpers │ └── tools/ │ ├── auth_tools.rb # authenticate │ ├── portfolio_tools.rb # holdings, positions, margins │ ├── order_tools.rb # place, modify, cancel, list, detail │ ├── smart_order_tools.rb # GTT, OCO (create, modify, cancel, list) │ ├── market_tools.rb # quote, LTP, OHLC, historical │ ├── option_chain_tools.rb # option chain, order trades, backtest │ ├── instrument_tools.rb # search, detail, CSV download │ └── user_tools.rb # profile ├── .env.example # Configuration template ├── Gemfile # Dependencies ├── groww-mcp.gemspec # Gem specification ├── LICENSE # MIT └── README.md # This file ``` ## Important Notes - **Access tokens expire daily at 6:00 AM IST.** TOTP auth handles this automatically. - **SEBI compliance**: Groww requires a static IP for order placement. Register yours at Trading APIs → "Add static IP". - **Live Data** (quotes, LTP, OHLC, historical) requires the ₹499/mo subscription. - **Order placement** executes real trades with real money. The AI will always confirm before placing orders. ## Other Groww MCP Servers Looking for alternatives? Here's every Groww MCP server available: | Project | Language | Tools | Highlights | Limitations | |---------|----------|:-----:|------------|-------------| | **[groww-mcp](https://github.com/developerjai/groww-mcp)** (this) | Ruby | 25 | Auto TOTP, GTT/OCO, option chain, backtest | — | | [darved2305/groww-mcp](https://github.com/darved2305/groww-mcp) | TypeScript | 23 | Mock mode, SIP/MF tools | Wrong API paths, broken endpoints | | [arkapravasinha/groww-mcp-server](https://github.com/arkapravasinha/groww-mcp-server) | Python | ~20 | 11 technical analysis tools | No auto-auth, no smart orders | | [venkatakaushikvemani/groww-mcp](https://github.com/venkatakaushikvemani/groww-mcp) | TypeScript | 8 | npm published, intent-based routing | Minimal tool set | | [karthik1729/groww-mcp](https://github.com/karthik1729/groww-mcp) | Go | 15 | Correct API paths, margin calculator | No auto-auth, no option chain | ## Built for Groww This project is built on top of the [Groww Trade API](https://groww.in/trade-api) to make algorithmic and AI-assisted trading accessible to every Groww user. **[@AskGroww](https://twitter.com/AskGroww)** — If you're from the Groww team, I'd love to collaborate. This MCP server makes your Trade API accessible to every AI assistant (Claude, GPT, Gemini) through the open [MCP standard](https://modelcontextprotocol.io/). Let's make Groww the most AI-friendly broker in India. ## Contributing Contributions are welcome! Whether it's a bug fix, new tool, documentation improvement, or feature idea — all PRs are appreciated. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. **Some ideas to get started:** - Add support for mutual fund tools (SIP, redemption, NAV) - Improve error messages and edge case handling - Add tests with mock API responses - Documentation and examples for different AI assistants ## License [MIT](LICENSE) — Jai Rajput ## Author **Jai Rajput** — CTO & AI Engineer - GitHub: [@developerjai](https://github.com/developerjai) - LinkedIn: [Jai Rajput](https://www.linkedin.com/in/developer-jairajput/) Building AI-powered tools for Indian markets. If this project helps you, consider giving it a star!