Architecture

Architecture

How It Works

AI Assistant (Claude/GPT)
        ↓ JSON-RPC 2.0 (stdio)
   Groww MCP Server (Ruby)
        ↓ HTTPS (Bearer token)
   Groww Trade API
        ↓
   Your Groww Account

1. The AI assistant sends MCP requests over stdio (JSON-RPC 2.0)
2. The MCP server processes the request, calls the Groww API
3. Results are formatted and returned to the AI assistant
4. The AI presents the data in natural language

Project Structure

groww-mcp/
├── bin/
│   └── groww-mcp                    # Entry point — loads env, authenticates, starts server
├── lib/
│   ├── groww_mcp.rb                 # Main module — ALL_TOOLS registry (25 tools)
│   └── groww_mcp/
│       ├── version.rb               # Gem version (1.0.0)
│       ├── auth.rb                  # Authentication — 3 methods, auto-refresh
│       ├── client.rb                # HTTP client — all Groww API endpoints
│       ├── base_tool.rb             # Base class — shared response/error helpers
│       └── tools/
│           ├── auth_tools.rb        # authenticate
│           ├── portfolio_tools.rb   # holdings, positions, margins, calculate_margin
│           ├── 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                     # Config template
├── Gemfile                          # Dependencies
├── groww-mcp.gemspec                # Gem spec
└── CONTRIBUTING.md                  # Contributor guidelines

Key Components

Authentication (lib/groww_mcp/auth.rb)

Manages 3 authentication methods with automatic token lifecycle:

• TOTP: Generates 6-digit code via ROTP gem → exchanges for access token
• Approval: SHA256(secret + timestamp) checksum → exchanges for access token
• Manual: Direct token passthrough

Token management:

• Tracks expiry timestamp from JWT payload
• Auto-refreshes 5 minutes before expiry via ensure_token!
• Called automatically before every API request

API Client (lib/groww_mcp/client.rb)

HTTP client using Ruby's net/http with SSL:

• Base URL: https://api.groww.in
• Headers: Authorization: Bearer <token>, X-API-VERSION: 1.0
• Retry logic: 3 attempts with exponential backoff
• Error classes: ApiError, RateLimitError (429), ForbiddenError (403)

Base Tool (lib/groww_mcp/base_tool.rb)

Every tool inherits from GrowwMcp::BaseTool which extends MCP::Tool:

• format_response(data) — converts API response to MCP text response (JSON formatted)
• error_response(error) — standardized error formatting

Tool Registry (lib/groww_mcp.rb)

All 25 tools are registered in GrowwMcp::ALL_TOOLS array. The entry point iterates this array to register each tool with the MCP server.

Dependencies

Gem	Purpose
mcp ~> 0.21	Official MCP Ruby SDK (by Anthropic + Shopify)
rotp ~> 6.3	TOTP code generation for automated auth

Design Decisions

Why Ruby?

• Official MCP Ruby SDK is mature and well-maintained
• Ruby's expressiveness keeps tool definitions clean and readable
• Strong HTTP/JSON ecosystem built into stdlib

Why not a gem?

• MCP servers run as standalone processes, not imported as libraries
• Direct cloning keeps credentials management simple
• Easier to customize for individual setups

Why 3 auth methods?

• TOTP is best but requires one-time setup
• Approval flow is Groww's default and many users already have API keys
• Manual token is useful for quick testing and debugging

Why separate tool files?

• Each file maps to one API category
• Easy to add new tools — create file, add to registry
• Clear ownership and focused code review