Indian Stock MCP Agent

印度经纪商MCP服务器

连接到印度代理平台的模型上下文协议（MCP）服务器-- 成长, Zerodha风筝，以及 INDmoney --通过Claude Code、Claude Desktop或任何兼容MCP的客户端提供您的金融投资组合的统一、只读视图。

不需要付费经纪人API订阅。服务器使用 Playwright浏览器自动化 在您通过可见的Chrome窗口登录后，从代理web应用程序中捕获数据。

______________________________________________________________________

特性

• 统一的投资组合视图 跨多个经纪人
• 股票、F&O、共同基金、美国股票、黄金 --所有资产类别
• 网络侦听 从代理SPA中捕获结构化JSON（比DOM抓取更可靠）
• 持续浏览器会话 --每次会话到期后登录一次
• 加密会话存储 （AES-256-GCM）存储在内存中
• 只读 --不下单，不转账
• 优雅降级 --如果一个代理失败，则返回部分数据

经纪人支持矩阵

______________________________________________________________________

先决条件

• Node.js 18+
• 谷歌浏览器 已安装（Playwright通过以下方式使用您的系统Chrome channel: 'chrome')
• 克劳德代码 或 克劳德桌面版 （或任何MCP客户端）

______________________________________________________________________

安装

git clone  indian-broker-mcp
cd indian-broker-mcp
npm install
npx playwright install chromium
npm run build

配置

复制示例env文件并根据需要进行编辑：

cp .env.example .env

环境变量

______________________________________________________________________

连接到MCP客户端

克劳德代码

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

克劳德桌面版

添加到您的Claude桌面配置(~/.config/claude/claude_desktop_config.json 在Linux上， ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

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

添加配置后重新启动Claude Desktop。

MCP检查员（用于测试）

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

在以下位置打开web UI http://localhost:5173 在那里你可以交互式地调用工具。

______________________________________________________________________

用法

步骤1：连接到经纪人

问克劳德：

“连接我到Zerodha”

这叫做 broker_connect 工具，其中：

1. 打开一个可见的Chrome窗口，进入经纪人的登录页面
2. 您手动登录（包括OTP/2FA）
3. 服务器自动检测登录成功并捕获会话

您还可以使用浏览器的DevTools中的Cookie进行连接：

“使用这些Cookie连接到Groww： `

`"

第二步：查询您的投资组合

连接后，自然地问：

• “我持有的股票是什么？”
• “在所有经纪人中显示我的共同基金投资组合”
• “我的投资组合总价值是多少？”
• “在Zerodha上显示我的F&O位置”
• “我持有哪些美国股票？”
• “显示今天的订单”
• “搜索信实股票”

步骤3：断开连接

“断开与Zerodha的连接”

这将擦除会话数据并删除该代理的浏览器配置文件。

______________________________________________________________________

工具参考

认证

投资组合（只读）

市场数据

发展

______________________________________________________________________

资源

MCP资源提供可通过URI访问的缓存数据：

______________________________________________________________________

建筑

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) │ │
│  └────────────────────────────┘ │
└─────────────────────────────────┘

数据提取是如何工作的

1. 导航 转到相关经纪人页面（例如，持股仪表板）
2. 拦截 SPA对其内部API做出的XHR/fetch响应
3. 解析 这些响应中的结构化JSON
4. 规范化 将特定于代理的字段转换为统一类型
5. 返回 以一致的格式发送给MCP客户端

网络拦截是主要策略，因为它直接从代理的内部API捕获干净、结构化的数据——比解析DOM可靠得多。

______________________________________________________________________

项目结构

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

______________________________________________________________________

会话管理

• 会话已存储 在内存中加密 使用AES-256-GCM
• 浏览器配置文件保存到磁盘 browser-data/{broker}/ 因此，Cookie在服务器重启后仍然有效
• 会话在配置的TTL后自动过期（默认值：6小时）
• 当会话到期时，下一个数据请求将返回一个错误，提示您重新连接
• broker_disconnect 安全地擦除内存中的会话和磁盘上的浏览器配置文件
• 每个代理在其自己的浏览器上下文中都是完全隔离的

典型会话寿命

______________________________________________________________________

发展

添加或更新代理抓取器

这 learn_broker_navigation 工具可帮助您发现和更新内部API端点：

1. 调用工具： learn_broker_navigation 随着 broker: "groww"
2. Chrome窗口打开——登录并导航到您关心的页面
3. 记录器捕获每个URL、XHR请求/响应和DOM状态
4. 录音保存到 recordings/{broker}/{timestamp}/
5. 使用捕获的数据进行更新 endpoints.ts 和 types.ts 对于那个经纪人

观看模式

npm run dev    # tsc --watch

关键设计决策

• DOM抓取的网络拦截：代理SPA通过内部REST API获取数据。拦截这些JSON响应比解析渲染的HTML更可靠、更结构化。
• 持久浏览器上下文：使用剧作家 launchPersistentContext 因此cookies/localStorage在重启后仍然有效。用户只需在会话到期时登录。
• 反侦测：使用真正的Chrome（不是Chromium），删除 webdriver 标志，在动作之间添加随机延迟。
• 灵活的响应解析：每个适配器的规范化器处理多个可能的响应形状（代理可能会更改其API结构）。字段通过回退链访问(raw.field1 ?? raw.field2 ?? default).

______________________________________________________________________

安全

• 未存储凭据 --您手动登录；仅捕获会话Cookie
• AES-256-GCM加密 对于所有内存会话数据
• Cookie和令牌永远不会被记录 --记录器编辑敏感数据
• 所有输出都进入stderr --stdout是为MCP JSON-RPC保留的（写入stdout会破坏协议）
• 浏览器配置文件被忽略 并在断开连接时删除
• 严格只读 --没有下单、修改头寸或转移资金的工具

______________________________________________________________________

局限性

• 浏览器抓取很脆弱 --代理UI和内部API如有更改，恕不另行通知。使用 learn_broker_navigation 当有东西坏了时重新校准。
• OTP登录需要用户在场 --Groww和INDmoney需要手动输入OTP。Zerodha需要TOTP/PIN码。
• 无实时流媒体 --通过导航到页面，按需获取数据。没有WebSocket或实时价格馈送。
• 速率限制 --避免快速连续调用投资组合工具。服务器在页面导航之间增加了延迟，但过度使用可能会触发代理反机器人措施。
• 服务条款 --自动访问代理网络应用程序可能会违反其条款。此工具仅供个人使用。
• 单用户 --服务器为每个代理管理一个会话。它不是为多用户或共享访问而设计的。

______________________________________________________________________

许可证

麻省理工学院