angleone-mcp-sever

An MCP (Model Context Protocol) server that exposes Angel One's SmartAPI as tools for Claude Code (or any MCP client) — login, portfolio data, market quotes, historical candles, and order placement/modification/cancellation.

⚠️ Order-related tools (place_order, modify_order, cancel_order) execute real trades on your Angel One account. Use with care.

Prerequisites

Python 3.10+
An Angel One trading account with SmartAPI access
- An API key generated at https://smartapi.angelbroking.com/apps
- TOTP enabled on your SmartAPI login (you'll need the base32 TOTP secret, not a 6-digit code)
Claude Code CLI, if you want to connect this as an MCP server

Setup

Clone the repo and install dependencies:

git clone https://github.com/bns218/angleone-mcp-sever.git
cd angleone-mcp-sever
pip install -r requirements.txt

Copy the env template and fill in your credentials:

cp .env.example .env

Edit .env:

SMARTAPI_API_KEY=your_api_key
SMARTAPI_CLIENT_CODE=your_client_code
SMARTAPI_PASSWORD=your_password
SMARTAPI_TOTP_SECRET=your_totp_base32_secret

.env is gitignored — never commit it.

Sanity-check the server starts:

cd mcp_server
python -c "import server; print('tools loaded ok')"

Connecting to Claude Code

Register the server with the Claude Code CLI. Use --scope project to make it available only in this directory, or --scope user to make it available in every Claude Code session on your machine.

claude mcp add angleone-smartapi --scope user -- python "/absolute/path/to/angleone-mcp-sever/mcp_server/server.py"

Verify it connected:

claude mcp list

You should see angleone-smartapi ... ✓ Connected.

Available tools

Tool	Description
`login`	Authenticate with SmartAPI using `.env` credentials (TOTP-based). Call first.
`logout`	Terminate the current session.
`get_profile`	Get account profile details.
`get_holdings`	Get current demat holdings.
`get_positions`	Get today's open positions.
`get_funds`	Get available margin/funds (RMS limits).
`get_order_book`	Get today's orders and statuses.
`get_trade_book`	Get today's executed trades.
`get_ltp`	Get last traded price for an exchange/symbol/token triple.
`get_price`	Get live LTP for a tracked stock/index by plain name (e.g. `"SBIN"`, `"NIFTY"`) — no token needed.
`get_historical_candle`	Get historical OHLCV candles by exchange/token.
`get_historical_by_symbol`	Get historical OHLCV candles by plain name. Supports daily (`ONE_DAY`) and intraday (`ONE_MINUTE`…`ONE_HOUR`) intervals.
`list_option_expiries`	List available derivative expiry dates for a stock/index.
`get_option_chain`	Get the CE/PE option chain (strikes + LTP) around spot for a stock/index.
`place_order`	Place a real order. Executes a real trade.
`modify_order`	Modify an existing open order. Affects a real order.
`cancel_order`	Cancel an open order. Cancels a real order.

get_price, get_historical_by_symbol, list_option_expiries, and get_option_chain resolve symbols against a local lookup (mcp_server/instruments.json + derivatives.json) covering:

The tracked NSE F&O stock list (208 symbols)
Main tradable indices with F&O contracts: NIFTY, BANKNIFTY, FINNIFTY, MIDCPNIFTY (NSE), SENSEX (BSE)
NSE sectoral indices, spot quote only, no F&O: NIFTY AUTO, NIFTY FMCG, NIFTY IT, NIFTY MEDIA, NIFTY METAL, NIFTY PHARMA, NIFTY PSU BANK, NIFTY PVT BANK, NIFTY REALTY, NIFTY ENERGY, NIFTY INFRA, NIFTY COMMODITIES, NIFTY CONSUMPTION, NIFTY MNC, NIFTY SERV SECTOR, NIFTY CPSE, NIFTY PSE

No live scrip search needed for any of the above — use the exact multi-word name for sectoral indices (e.g. "NIFTY PSU BANK").

Claude Code Skill

A companion skill at ~/.claude/skills/nse-fo-quotes/SKILL.md (user scope) tells Claude to answer price/candle/option-chain questions for the tracked symbol list directly using these tools, without asking for exchange/token details first. It's independent of this repo — copy the skill file if you set the server up on another machine.

Project structure

mcp_server/
  server.py             # FastMCP server exposing SmartAPI operations as MCP tools
  smartapi_client.py    # Thin wrapper around the smartapi-python SDK
  instruments.json       # Local symbol -> {exchange, tradingsymbol, token} lookup
  derivatives.json       # Local option/future contract lookup per underlying
  build_instruments.py   # Regenerates the two files above from Angel One's instrument master
requirements.txt
.env.example              # Credential template (copy to .env)
.mcp.json                  # Claude Code project-scope MCP registration

Updating the tracked symbol list

instruments.json and derivatives.json are static snapshots. To refresh them (new F&O stocks added/removed, or the derivatives file goes stale near month-end rollovers):

Edit FNO_STOCKS / INDEX_NAMES in mcp_server/build_instruments.py if the symbol list changed.

Download the current instrument master and rebuild:

cd mcp_server
python -c "import requests; open('OpenAPIScripMaster.json','wb').write(requests.get('https://margincalculator.angelbroking.com/OpenAPI_File/files/OpenAPIScripMaster.json').content)"
python build_instruments.py
rm OpenAPIScripMaster.json

Notes

Login re-authenticates and replaces the session each time it's called; safe to call repeatedly — and every tool auto-logs in on first use if no session exists yet.
For symbols outside the tracked list, use SmartAPI's scrip search (or the Angel One instrument master) to look up tokens, then call get_ltp / get_historical_candle directly with exchange + token.