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

Related MCP server: Kite 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

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.