Angel One
Angel One SmartAPI MCP for orders, portfolio, market data, GTT rules, charges, and margin.
Open source Open in the app JSON README (API)
About
Angel One SmartAPI MCP for orders, portfolio, market data, GTT rules, charges, and margin.
Details
- Kind
- MCP servers
- Topic
- Finance & crypto
- Publisher
- ameernoufil
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.10
- Last push
- 2026-05-22T17:28:28Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:24
- Updated
- 2026-08-29 03:02:24
- Origin id
io.github.ameernoufil/angel-one
README
# Angel One MCP Server
[](https://www.npmjs.com/package/angel-one-mcp)
[](https://registry.modelcontextprotocol.io/)
TypeScript [Model Context Protocol](https://modelcontextprotocol.io) server for [Angel One SmartAPI](https://smartapi.angelone.in/).
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`](https://www.npmjs.com/package/angel-one-mcp)
- Official MCP Registry: [`io.github.ameernoufil/angel-one`](https://registry.modelcontextprotocol.io/)
- GitHub repo: [`ameernoufil/angel-one-mcp`](https://github.com/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:
```json
{
"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
```bash
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`:
```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`](docs/llm-setup.md).
## Development
Requirements:
- Node.js 18+
Commands:
```bash
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](LICENSE)