# 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](https://smartapi.angelbroking.com/) 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](https://claude.com/claude-code) CLI, if you want to connect this as an MCP server

## Setup

1. Clone the repo and install dependencies:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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.

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

Verify it connected:

```bash
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:

   ```bash
   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](https://margincalculator.angelbroking.com/OpenAPI_File/files/OpenAPIScripMaster.json))
  to look up tokens, then call `get_ltp` / `get_historical_candle` directly with exchange + token.