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

1. 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
   

2. 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.

3. 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):

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

2. 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.