Angel One

Angel One MCP Server

[npm] [MCP Registry]

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.gitcd angel-one-mcpnpm installcp .env.example .envnpm run buildnpm 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_keyANGEL_CLIENT_ID=your_client_idANGEL_PASSWORD=your_mpinANGEL_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 installnpm run buildnpm run lintnpm run lint:fixnpm run formatnpm run devnpm 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