Angel One MCP Server

TypeScript Model Context Protocol server for Angel One SmartAPI.

Use it from Claude, Cursor, Copilot, or any MCP client to:

• place and manage orders
• read holdings, positions, and funds
• fetch market data, candles, OI, Greeks, and movers
• manage GTT rules
• estimate charges and margin

Highlights

• Direct fetch() integration. No Angel One SDK dependency.
• Auto TOTP generation from your base32 secret.
• Lazy login with token refresh in API layer.
• Safety guard for trading mutations with soft and hard limits.
• stdio MCP server. Works well with npx.

Discoverability

• npm package: angel-one-mcp
• Official MCP Registry: io.github.ameernoufil/angel-one
• GitHub repo: ameernoufil/angel-one-mcp

If your client supports registry-based discovery, search for io.github.ameernoufil/angel-one. If your client prefers package installs, use angel-one-mcp from npm.

Quick Start

Option A: Use with npx (recommended)

Add this to your MCP client config:

{
  "mcpServers": {
    "angel-one": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "angel-one-mcp"],
      "env": {
        "ANGEL_API_KEY": "your_smartapi_key",
        "ANGEL_CLIENT_ID": "your_client_id",
        "ANGEL_PASSWORD": "your_mpin",
        "ANGEL_TOTP_SECRET": "your_base32_totp_secret"
      }
    }
  }
}

Option B: Run from source

git clone https://github.com/ameernoufil/angel-one-mcp.git
cd angel-one-mcp
npm install
cp .env.example .env
npm run build
npm start

If running from source, point your MCP client to build/index.js.

Environment Variables

Required:

• ANGEL_API_KEY
• ANGEL_CLIENT_ID
• ANGEL_PASSWORD
• ANGEL_TOTP_SECRET

Optional safety limits:

• SOFT_MAX_ORDER_QTY default 25
• HARD_MAX_ORDER_QTY default 100
• SOFT_MAX_ORDER_VALUE default 10000
• HARD_MAX_ORDER_VALUE default 100000

Example .env:

ANGEL_API_KEY=your_smartapi_key
ANGEL_CLIENT_ID=your_client_id
ANGEL_PASSWORD=your_mpin
ANGEL_TOTP_SECRET=your_base32_totp_secret

Safety Model

Trading mutations are guarded.

Soft limits block by default and can be overridden with force: true. Hard limits cannot be bypassed without changing env vars and restarting the server.

Guarded operations include:

• place_order
• modify_order
• create_gtt_rule
• modify_gtt_rule
• convert_position

For MARKET orders, the server attempts LTP-based value checks before allowing the request.

Tool Coverage

• Auth: login and logout
• Portfolio: holdings, positions, funds, conversion
• Orders: place, modify, cancel, book lookup, trade lookup
• Market: search, LTP, quotes, candles, OI, Greeks, movers, PCR
• GTT: create, modify, cancel, list, inspect
• Calculator: margin and brokerage estimates
• User: profile

For an agent-focused onboarding prompt, see docs/llm-setup.md.

Development

Requirements:

• Node.js 18+

Commands:

npm install
npm run build
npm run lint
npm run lint:fix
npm run format
npm run dev
npm start

Architecture Notes

• Entry point: src/index.ts
• API client and auth flow: src/api.ts
• Config and safety limits: src/config.ts
• Order guard: src/guards.ts
• Tool registration: src/tools/index.ts
• Tool implementations: src/tools/*.ts

License

MIT