groww-mcp

Groww MCP Server

The most complete MCP server for Groww — 25 tools, automated TOTP auth, smart orders (GTT/OCO), option chain with Greeks, and local instrument search. No other Groww MCP has all of these.

A Model Context Protocol (MCP) server that connects AI assistants (Claude, GPT, Gemini) to the Groww 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.

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 (TS)	arkapravasinha (Python)	karthik1729 (Go)
Tools	25	23	~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 (local, CSV-based)	✅	❌	✅	❌
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 trading account with API access

Installation

Install from RubyGems:

gem install groww-mcp

Or run from source:

git clone https://github.com/developerjai/groww-mcp.git
cd groww-mcp
bundle install

Configuration

cp .env.example .env

Edit .env with your Groww credentials (see Authentication below).

Connect to Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "groww": {
      "type": "stdio",
      "command": "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:

{
  "mcpServers": {
    "groww": {
      "command": "groww-mcp"
    }
  }
}

Running from source instead of the gem? Use "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 → 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:

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 → Settings → Trading APIs
2. Click "Generate API key" → Create a key
3. Copy the API Key and API Secret
4. Add to .env:

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 → Settings → Trading APIs
2. Click "Generate API key" dropdown → "Generate Access Token"
3. Copy the token
4. Add to .env:

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 for a basket of orders before placing them

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 for an expiry with OI, IV, and Greeks (Δ, Γ, Θ, ν)
get_greeks	Greeks (Δ, Γ, Θ, ν, ρ) and IV for a specific option contract
get_historical_data	Historical candlestick data for analysis (custom intervals supported)

Market data tools require the Groww Live Data subscription (₹499 + GST/month). Without it, these tools will return a clear error message explaining how to subscribe.

Instruments (Free)

Instrument lookup runs locally against Groww's public instruments CSV (cached for 24h) — fast, and no Live Data subscription needed.

Tool	Description
search_instruments	Find stocks, F&O, ETFs by name or symbol (local CSV search)
get_instrument_detail	Lot size, tick size, expiry, contract details (local CSV lookup)
download_instruments	Complete CSV of all tradable instruments

Note on backtesting: the Groww API does not offer a backtesting endpoint, so this server doesn't ship a run_backtest tool. Use get_historical_data to pull candles and let your AI assistant run the analysis.

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, Greeks, order trades
│           ├── instrument_tools.rb    # local 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 (this)	Ruby	25	Auto TOTP, GTT/OCO, option chain + Greeks, local instrument search	—
darved2305/groww-mcp	TypeScript	23	Mock mode, SIP/MF tools	No auto-auth, no smart orders
arkapravasinha/groww-mcp-server	Python	~20	11 technical analysis tools	No auto-auth, no smart orders
venkatakaushikvemani/groww-mcp	TypeScript	8	npm published, intent-based routing	Minimal tool set
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 to make algorithmic and AI-assisted trading accessible to every Groww user.

@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. 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 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

Author

Building AI-powered tools for Indian markets.