groww-mcp 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85f7916a5021489757b9b108c915bd191f3bc09bc21fa39bfb60508db5710e94
+  data.tar.gz: c57656b6ce73bd2497a6720f34e51c01fc473db1a028114aeec17ec11d9fbf0b
+SHA512:
+  metadata.gz: 3079e0713ab14eadc60ad0c38354714eda6fd0e405f67f597e07eda7a795ce71d533b30a7e10c549366b52643618eb67a420692edc10d4b88811fc5848bbbf23
+  data.tar.gz: 94ec58d7f5ef2635f065f7b139bdcda0ce6e4dc0afaeb298cbf83818fdd404be5400bf19d99aee166aab7ff32ac76b96020f0cb0cca286e4e0d328f358645609

data/.env.example

@@ -0,0 +1,19 @@
+# Groww MCP Configuration
+# Copy this file to .env and fill in your credentials
+# See README.md for setup instructions
+
+# === Authentication (choose one method) ===
+
+# Method 1: TOTP (Recommended — fully automated, no daily manual steps)
+# Get these from: Groww App → Settings → Trading APIs → Generate TOTP token
+GROWW_TOTP_KEY=your_totp_api_key_here
+GROWW_TOTP_SECRET=your_totp_qr_code_secret_here
+
+# Method 2: API Key + Secret (Requires daily approval on Groww website)
+# Get these from: Groww App → Settings → Trading APIs → Generate API key
+# GROWW_API_KEY=your_api_key_here
+# GROWW_API_SECRET=your_api_secret_here
+
+# Method 3: Direct Access Token (Manual — expires daily at 6:00 AM IST)
+# Get from: Groww App → Settings → Trading APIs → Generate Access Token
+# GROWW_ACCESS_TOKEN=your_access_token_here

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-07-28
+
+First public release.
+
+### Added
+
+- 25 MCP tools across 8 categories:
+  - **Auth** — `authenticate`
+  - **Portfolio** — `get_holdings`, `get_positions`, `get_margins`, `calculate_margin`
+  - **Orders** — `get_orders`, `get_order_detail`, `get_order_trades`, `place_order`, `modify_order`, `cancel_order`
+  - **Smart Orders (GTT/OCO)** — `get_smart_orders`, `create_smart_order`, `modify_smart_order`, `cancel_smart_order`
+  - **Market Data** — `get_quote`, `get_ltp`, `get_ohlc`, `get_option_chain`, `get_greeks`, `get_historical_data`
+  - **Instruments** — `search_instruments`, `get_instrument_detail`, `download_instruments`
+  - **User** — `get_profile`
+- 3 authentication methods: TOTP (fully automated), API Key + Secret (approval flow), direct access token
+- Auto token refresh with 5-minute expiry buffer
+- Option chain with Greeks (Delta, Gamma, Theta, Vega)
+- Local CSV-based instrument search — no API calls needed for symbol lookup
+- Rate limit handling with exponential backoff
+- Clear error messages for endpoints that require a paid Groww API subscription
+
+### Fixed (pre-release hardening)
+
+- Critical order-safety bugs in the API client and order tools
+- All endpoint paths aligned with the official Groww API (holdings, orders, market data, option chain)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jai Rajput
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,308 @@
+# Groww MCP Server
+
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.1-red?logo=ruby)](https://www.ruby-lang.org/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-blue?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0id2hpdGUiLz48L3N2Zz4=)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Groww API](https://img.shields.io/badge/Groww-Trade%20API-00d09c?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==)](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 local instrument search. 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 | ~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](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 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](https://groww.in/trade-api) (₹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](https://github.com/developerjai/groww-mcp)** (this) | Ruby | 25 | Auto TOTP, GTT/OCO, option chain + Greeks, local instrument search | — |
+| [darved2305/groww-mcp](https://github.com/darved2305/groww-mcp) | TypeScript | 23 | Mock mode, SIP/MF tools | No auto-auth, no smart orders |
+| [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)
+
+## Author
+
+Building AI-powered tools for Indian markets.

data/bin/groww-mcp

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "mcp"
+require_relative "../lib/groww_mcp"
+
+# Load .env file if present
+env_file = File.join(__dir__, "..", ".env")
+if File.exist?(env_file)
+  File.readlines(env_file).each do |line|
+    line = line.strip
+    next if line.empty? || line.start_with?("#")
+
+    key, value = line.split("=", 2)
+    ENV[key] = value if key && value
+  end
+end
+
+# Initialize auth and client
+auth = GrowwMcp::Auth.new
+client = GrowwMcp::Client.new(auth)
+
+# Auto-authenticate on startup
+begin
+  auth.authenticate!
+rescue GrowwMcp::AuthError => e
+  $stderr.puts "[groww-mcp] Warning: #{e.message}"
+  $stderr.puts "[groww-mcp] Tools will attempt authentication on first use."
+end
+
+# Create MCP server
+server = MCP::Server.new(
+  name: "groww-mcp",
+  version: GrowwMcp::VERSION,
+  tools: GrowwMcp::ALL_TOOLS,
+  server_context: { auth: auth, client: client },
+)
+
+$stderr.puts "[groww-mcp] Groww MCP Server v#{GrowwMcp::VERSION}"
+$stderr.puts "[groww-mcp] #{GrowwMcp::ALL_TOOLS.length} tools registered"
+$stderr.puts "[groww-mcp] Auth: #{auth.access_token ? 'connected' : 'pending'}"
+
+# Start stdio transport
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open

data/lib/groww_mcp/auth.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "digest"
+require "rotp"
+
+module GrowwMcp
+  class Auth
+    TOKEN_ENDPOINT = "/v1/token/api/access"
+    BASE_URL = "https://api.groww.in"
+
+    attr_reader :access_token, :token_expiry
+
+    def initialize
+      @access_token = nil
+      @token_expiry = nil
+    end
+
+    # Authenticate using the best available method
+    # Priority: Direct token > TOTP > API Key + Secret
+    def authenticate!
+      if ENV["GROWW_ACCESS_TOKEN"] && !ENV["GROWW_ACCESS_TOKEN"].empty?
+        @access_token = ENV["GROWW_ACCESS_TOKEN"]
+        @token_expiry = nil # Unknown expiry for manual tokens
+        log "Authenticated with direct access token"
+      elsif ENV["GROWW_TOTP_KEY"] && ENV["GROWW_TOTP_SECRET"]
+        authenticate_totp!
+      elsif ENV["GROWW_API_KEY"] && ENV["GROWW_API_SECRET"]
+        authenticate_approval!
+      else
+        raise AuthError, "No credentials configured. Set GROWW_TOTP_KEY + GROWW_TOTP_SECRET (recommended), " \
+                         "or GROWW_API_KEY + GROWW_API_SECRET, or GROWW_ACCESS_TOKEN in your .env file."
+      end
+
+      @access_token
+    end
+
+    # Check if token needs refresh (expired or expiring in 5 minutes)
+    def token_valid?
+      return false unless @access_token
+      return true unless @token_expiry # Manual tokens — assume valid
+
+      Time.now < (@token_expiry - 300) # 5 minute buffer
+    end
+
+    # Ensure we have a valid token, refresh if needed
+    def ensure_token!
+      authenticate! unless token_valid?
+      @access_token
+    end
+
+    # Drop the cached token so the next ensure_token! re-authenticates.
+    # Called by the client when the API returns 401 (stale/expired token).
+    def invalidate!
+      @access_token = nil
+      @token_expiry = nil
+    end
+
+    private
+
+    # TOTP-based authentication (fully automated, no manual steps)
+    def authenticate_totp!
+      totp = ROTP::TOTP.new(ENV["GROWW_TOTP_SECRET"])
+      code = totp.now
+
+      body = { key_type: "totp", totp: code }
+      result = post_token(ENV["GROWW_TOTP_KEY"], body)
+
+      @access_token = result["token"]
+      @token_expiry = Time.parse(result["expiry"]) if result["expiry"]
+
+      log "Authenticated via TOTP (expires: #{result['expiry']})"
+    end
+
+    # API Key + Secret authentication (requires daily approval on Groww website)
+    def authenticate_approval!
+      timestamp = Time.now.to_i.to_s
+      checksum = Digest::SHA256.hexdigest("#{ENV['GROWW_API_SECRET']}#{timestamp}")
+
+      body = { key_type: "approval", checksum: checksum, timestamp: timestamp }
+      result = post_token(ENV["GROWW_API_KEY"], body)
+
+      @access_token = result["token"]
+      @token_expiry = Time.parse(result["expiry"]) if result["expiry"]
+
+      log "Authenticated via API Key approval (expires: #{result['expiry']})"
+    end
+
+    def post_token(api_key, body)
+      uri = URI("#{BASE_URL}#{TOKEN_ENDPOINT}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Post.new(uri.path)
+      request["Authorization"] = "Bearer #{api_key}"
+      request["Content-Type"] = "application/json"
+      request["X-API-VERSION"] = "1.0"
+      request.body = body.to_json
+
+      response = http.request(request)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        error_body = JSON.parse(response.body) rescue {}
+        message = error_body.dig("error", "errorMessage") || error_body.dig("error", "message") || response.body
+        raise AuthError, "Token generation failed (#{response.code}): #{message}"
+      end
+
+      JSON.parse(response.body)
+    end
+
+    def log(message)
+      $stderr.puts "[groww-mcp] #{message}"
+    end
+  end
+
+  class AuthError < StandardError; end
+end

data/lib/groww_mcp/base_tool.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "mcp"
+require "json"
+
+module GrowwMcp
+  # Extend MCP::Tool with response helpers used by all Groww tools
+  class BaseTool < MCP::Tool
+    class << self
+      private
+
+      def format_response(data)
+        text = JSON.pretty_generate(data)
+        MCP::Tool::Response.new([{ type: "text", text: text }])
+      end
+
+      def error_response(error)
+        MCP::Tool::Response.new([{ type: "text", text: "❌ #{error.message}" }])
+      end
+    end
+  end
+end