# Groww MCP Server

An MCP (Model Context Protocol) server for the [Groww](https://groww.in) trading platform. This enables LLM applications to interact with your Groww trading account.

## Features

- **Orders**: Place, modify, cancel, and list orders across Equity, F&O, and Commodities
- **Portfolio**: View holdings and positions
- **Market Data**: Get quotes, LTP, OHLC, and historical candle data
- **Instruments**: Search and lookup trading instruments
- **Margin**: Check available margin and calculate order margin requirements
- **Live Feeds**: Subscribe to real-time price updates via WebSocket

## Installation

### Using Docker (Recommended)

```bash
docker pull abhijeet45/growwmcp:latest
```

### Using uvx

```bash
uvx --from git+https://github.com/abhijeetmohanan/growwmcp.git growmcp
```

### Using pip

```bash
pip install git+https://github.com/abhijeetmohanan/growwmcp.git
```

### From source

```bash
git clone https://github.com/abhijeetmohanan/growwmcp.git
cd growwmcp
pip install -e .
```

## Configuration

### Environment Variables

Set your Groww API credentials:

```bash
# Option 1: API Key + Secret (requires daily approval)
export GROWW_API_KEY=your_api_key
export GROWW_API_SECRET=your_api_secret

# Option 2: TOTP Flow (no expiry - recommended)
export GROWW_TOTP_TOKEN=your_totp_token
export GROWW_TOTP_SECRET=your_totp_secret
```

Get your API credentials from [Groww Trade API](https://groww.in/trade-api).

### MCP Configuration

Add to your `.mcp.json` (project-level) or MCP client config:

**Using Docker:**
```json
{
  "mcpServers": {
    "groww": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "GROWW_API_KEY", "-e", "GROWW_API_SECRET", "abhijeet45/growwmcp:latest"],
      "env": {
        "GROWW_API_KEY": "${GROWW_API_KEY}",
        "GROWW_API_SECRET": "${GROWW_API_SECRET}"
      }
    }
  }
}
```

**Using uvx:**
```json
{
  "mcpServers": {
    "groww": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/abhijeetmohanan/growwmcp.git", "growmcp"],
      "env": {
        "GROWW_API_KEY": "${GROWW_API_KEY}",
        "GROWW_API_SECRET": "${GROWW_API_SECRET}"
      }
    }
  }
}
```

## Available Tools

### Order Management
| Tool | Description |
|------|-------------|
| `place_order` | Place a new order (BUY/SELL) |
| `modify_order` | Modify an existing order |
| `cancel_order` | Cancel a pending order |
| `get_order_list` | List all orders (pending, executed, cancelled) |
| `get_order_status` | Get status of a specific order |
| `get_order_detail` | Get detailed order information |
| `get_trades_for_order` | Get trades executed for an order |

### Portfolio
| Tool | Description |
|------|-------------|
| `get_holdings` | Get DEMAT holdings |
| `get_positions` | Get current positions |
| `get_position_by_symbol` | Get position for specific symbol |

### Market Data
| Tool | Description |
|------|-------------|
| `get_quote` | Get real-time quote for an instrument |
| `get_ltp` | Get last traded price (up to 50 symbols) |
| `get_ohlc` | Get OHLC data (up to 50 symbols) |
| `get_historical_candles` | Get historical candle data |

### Instruments
| Tool | Description |
|------|-------------|
| `search_instrument_by_groww_symbol` | Search by Groww symbol |
| `search_instrument_by_trading_symbol` | Search by exchange + trading symbol |
| `search_instrument_by_exchange_token` | Search by exchange token |
| `search_instruments` | Search instruments by pattern |
| `get_all_instruments_summary` | Get instrument database summary |

### Margin
| Tool | Description |
|------|-------------|
| `get_available_margin` | Get available margin across segments |
| `calculate_order_margin` | Calculate margin required for an order |

### Live Feeds (WebSocket)
| Tool | Description |
|------|-------------|
| `subscribe_ltp` | Subscribe to LTP updates |
| `get_live_ltp` | Get live LTP from subscriptions |
| `unsubscribe_ltp` | Unsubscribe from LTP updates |
| `subscribe_market_depth` | Subscribe to order book updates |
| `get_market_depth` | Get live market depth |
| `subscribe_index_value` | Subscribe to index updates |
| `get_index_value` | Get live index values |
| `subscribe_order_updates` | Subscribe to order status updates |
| `subscribe_position_updates` | Subscribe to position updates |

## Usage Examples

Once configured, you can interact with your trading account:

- "What are my stock holdings?"
- "What are my pending orders?"
- "Buy 10 shares of RELIANCE at market price"
- "What's the current price of TCS?"
- "Show me the historical data for NIFTY"
- "How much margin do I have available?"
- "Search for silver ETFs"

## Supported Exchanges & Segments

| Exchange | Segments |
|----------|----------|
| NSE | CASH, FNO |
| BSE | CASH |
| MCX | COMMODITY |

## Rate Limits

| Category | Per Second | Per Minute |
|----------|------------|------------|
| Orders | 15 | 250 |
| Live Data | 10 | 300 |
| Non-Trading | 20 | 500 |

Live feed: max 1000 concurrent subscriptions.

## Important Notes

- **TPIN Verification**: Selling DEMAT holdings requires manual TPIN verification via Groww app/website. This cannot be automated via API.
- **API Approval**: If using API Key + Secret method, you need to approve access daily on Groww.
- **Market Hours**: Orders can only be placed during market hours (9:15 AM - 3:30 PM IST). AMO (After Market Orders) are queued for next trading day.