Indian Broker MCP Server

A Model Context Protocol (MCP) server that connects to Indian broker platforms — Groww, Zerodha Kite, and INDmoney — to provide a unified, read-only view of your financial portfolio through Claude Code, Claude Desktop, or any MCP-compatible client.

No paid broker API subscriptions required. The server uses Playwright browser automation to capture data from the broker web apps after you log in via a visible Chrome window.

Features

• Unified portfolio view across multiple brokers
• Stocks, F&O, Mutual Funds, US Stocks, Gold — all asset classes
• Network interception captures structured JSON from broker SPAs (more reliable than DOM scraping)
• Persistent browser sessions — log in once per session expiry
• Encrypted session storage (AES-256-GCM) in memory
• Read-only — no order placement, no fund transfers
• Graceful degradation — partial data returned if one broker fails

Broker Support Matrix

Prerequisites

• Node.js 18+
• Google Chrome installed (Playwright uses your system Chrome via channel: 'chrome')
• Claude Code or Claude Desktop (or any MCP client)

Installation

git clone <repo-url> indian-broker-mcp
cd indian-broker-mcp
npm install
npx playwright install chromium
npm run build

Configuration

Copy the example env file and edit as needed:

cp .env.example .env

Environment Variables

Connecting to an MCP Client

Claude Code

claude mcp add indian-broker -- node /path/to/indian-broker-mcp/build/index.js

Claude Desktop

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "indian-broker": {
      "command": "node",
      "args": ["/path/to/indian-broker-mcp/build/index.js"]
    }
  }
}

Restart Claude Desktop after adding the configuration.

MCP Inspector (for testing)

npx @modelcontextprotocol/inspector node ./build/index.js

Opens a web UI at http://localhost:5173 where you can call tools interactively.

Usage

Step 1: Connect to a broker

Ask Claude:

"Connect me to Zerodha"

This calls the broker_connect tool, which:

1. Opens a visible Chrome window to the broker's login page
2. You log in manually (including OTP / 2FA)
3. The server detects login success automatically and captures the session

You can also connect using cookies from your browser's DevTools:

"Connect to Groww using these cookies: <paste from document.cookie>"

Step 2: Query your portfolio

Once connected, ask naturally:

• "What are my stock holdings?"
• "Show my mutual fund portfolio across all brokers"
• "What's my total portfolio value?"
• "Show my F&O positions on Zerodha"
• "What US stocks do I hold?"
• "Show today's orders"
• "Search for Reliance stock"

Step 3: Disconnect

"Disconnect from Zerodha"

This wipes the session data and deletes the browser profile for that broker.

Tools Reference

Authentication

Portfolio (Read-Only)

Market Data

Development

Resources

MCP Resources provide cached data accessible by URI:

Architecture

MCP Client (Claude Code / Desktop)
        │
        │ STDIO (JSON-RPC)
        ▼
┌─────────────────────────────────┐
│       MCP Server (Node.js)      │
│                                 │
│  ┌─────────┐ ┌───────┐ ┌─────┐ │
│  │  Groww   │ │Zerodha│ │ IND │ │
│  │ Adapter  │ │Adapter│ │money│ │
│  └────┬─────┘ └───┬───┘ └──┬──┘ │
│       │           │        │    │
│  ┌────▼───────────▼────────▼──┐ │
│  │   Playwright (Chrome)      │ │
│  │   • Network interception   │ │
│  │   • Page navigation        │ │
│  │   • Persistent contexts    │ │
│  └────────────────────────────┘ │
│                                 │
│  ┌────────────────────────────┐ │
│  │  Session Store (encrypted) │ │
│  └────────────────────────────┘ │
└─────────────────────────────────┘

How data extraction works

1. Navigate to the relevant broker page (e.g., holdings dashboard)
2. Intercept the XHR/fetch responses the SPA makes to its internal APIs
3. Parse the structured JSON from those responses
4. Normalize broker-specific fields into unified types
5. Return to the MCP client in a consistent format

Network interception is the primary strategy because it captures clean, structured data directly from the broker's internal APIs — far more reliable than parsing the DOM.

Project Structure

src/
├── index.ts                    # Entry point (STDIO transport)
├── server.ts                   # MCP server, tool/resource registration
├── types/
│   ├── portfolio.ts            # Holding, Position, MutualFundHolding, etc.
│   ├── broker.ts               # BrokerAdapter interface
│   └── auth.ts                 # Session types
├── adapters/
│   ├── base.ts                 # Abstract base adapter
│   ├── groww/
│   │   ├── index.ts            # Adapter + normalizers
│   │   ├── scraper.ts          # Network interception logic
│   │   ├── endpoints.ts        # URL patterns
│   │   ├── selectors.ts        # DOM selectors (fallback)
│   │   └── types.ts            # Raw API response types
│   ├── zerodha/                # Same structure
│   └── indmoney/               # Same structure
├── browser/
│   ├── manager.ts              # Browser lifecycle, persistent contexts
│   ├── auth-flow.ts            # Login detection + session capture
│   ├── interceptor.ts          # XHR/fetch response capture engine
│   ├── recorder.ts             # Navigation recorder for development
│   └── helpers.ts              # Utilities (delays, screenshots)
├── auth/
│   ├── crypto.ts               # AES-256-GCM encrypt/decrypt
│   └── session-store.ts        # In-memory encrypted session store
├── normalizer/
│   └── index.ts                # Portfolio summary aggregation
└── utils/
    ├── logger.ts               # stderr-only logger
    ├── config.ts               # .env config loader
    └── retry.ts                # Exponential backoff retry

Session Management

• Sessions are stored encrypted in memory using AES-256-GCM
• Browser profiles are persisted to disk under browser-data/{broker}/ so cookies survive server restarts
• Sessions auto-expire after the configured TTL (default: 6 hours)
• When a session expires, the next data request will return an error prompting you to reconnect
• broker_disconnect securely wipes both the in-memory session and the on-disk browser profile
• Each broker is fully isolated in its own browser context

Typical session lifetimes

Development

Adding or updating broker scrapers

The learn_broker_navigation tool helps you discover and update internal API endpoints:

1. Call the tool: learn_broker_navigation with broker: "groww"
2. A Chrome window opens — log in and navigate to the pages you care about
3. The recorder captures every URL, XHR request/response, and DOM state
4. Recordings are saved to recordings/{broker}/{timestamp}/
5. Use the captured data to update endpoints.ts and types.ts for that broker

Watch mode

npm run dev    # tsc --watch

Key design decisions

• Network interception over DOM scraping: Broker SPAs fetch data via internal REST APIs. Intercepting those JSON responses is more reliable and structured than parsing rendered HTML.
• Persistent browser contexts: Using Playwright's launchPersistentContext so cookies/localStorage survive restarts. The user only needs to log in when the session expires.
• Anti-detection: Uses real Chrome (not Chromium), removes webdriver flag, adds random delays between actions.
• Flexible response parsing: Each adapter's normalizer handles multiple possible response shapes (brokers may change their API structure). Fields are accessed with fallback chains (raw.field1 ?? raw.field2 ?? default).

Security

• No credentials stored — you log in manually; only session cookies are captured
• AES-256-GCM encryption for all in-memory session data
• Cookies and tokens are never logged — the logger redacts sensitive data
• All output goes to stderr — stdout is reserved for MCP JSON-RPC (writing to stdout would break the protocol)
• Browser profiles are gitignored and deleted on disconnect
• Strictly read-only — there are no tools for placing orders, modifying positions, or transferring funds

Limitations

• Browser scraping is fragile — broker UIs and internal APIs change without notice. Use learn_broker_navigation to recalibrate when something breaks.
• OTP login requires user presence — Groww and INDmoney require manual OTP entry. Zerodha requires TOTP/PIN.
• No real-time streaming — data is fetched on demand by navigating to pages. There is no WebSocket or live price feed.
• Rate limiting — avoid calling portfolio tools in rapid succession. The server adds delays between page navigations but aggressive use may trigger broker anti-bot measures.
• Terms of Service — automated access to broker web apps may violate their terms. This tool is intended for personal use only.
• Single user — the server manages one session per broker. It is not designed for multi-user or shared access.

License

MIT