angelone-mcp

An MCP (Model Context Protocol) server that wraps Angel One's SmartAPI —

trading, portfolio, market data, GTT rules, and margin/brokerage — so any MCP

client (Claude, Claude Code, etc.) can query your account and place orders

through natural conversation.

⚠️ This places real orders on a real trading account. Test with small

quantities first, and keep in mind Angel One (like most brokers) does not

let you "undo" a filled order.

What's included

• `angelone_mcp/client.py` – REST client for every documented SmartAPI route:

auth, orders, positions/holdings, GTT rules, historical candles/OI,

quotes, option greeks, gainers/losers, margin calculator, brokerage

estimator. Handles TOTP login, auto re-login on token expiry, and paces

itself against SmartAPI's documented rate limits (see "Rate limiting"

below).

• `angelone_mcp/server.py` – MCP server exposing 32 tools built on top of

the client (see full list below).

1. Prerequisites

• Python 3.10+
• An Angel One trading account with SmartAPI access
• A SmartAPI app created at https://smartapi.angelone.in/ (gives you an API key)
• TOTP set up on your Angel One account, and the base32 secret used to

set up that authenticator (not the 6-digit code — the secret behind it).

You get this once, when you first scan the QR code to enable TOTP; if you

don't have it saved, you'll need to reset/reconfigure TOTP on your account

to get a fresh secret.

2. Install

cd angelone-mcp
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Configure credentials

Set these environment variables (e.g. in a `.env` file you source, or

directly in your MCP client config):

Never commit these to source control. Treat `ANGELONE_TOTP_SECRET` and

`ANGELONE_PIN` like passwords — anyone with them plus your API key can trade

on your account.

Optional: running behind an HTTP proxy

If your machine/network requires an outbound HTTP proxy to reach the

internet, set:

These are only needed if the standard `HTTP_PROXY` / `HTTPS_PROXY` environment

variables aren't already visible to the server process. That's commonly the

case for MCP servers, since MCP clients usually launch the server with an

explicit `env` block (like the JSON below) instead of inheriting your shell's

environment — so a proxy configured in your shell won't reach the server

unless you either add it to that `env` block yourself under `HTTPS_PROXY`, or

use the `ANGELONE_*` variables above. If neither `ANGELONE_HTTP_PROXY` nor

`ANGELONE_HTTPS_PROXY` is set, the server falls back to the standard

`HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` variables automatically.

4. Run it

Standalone (for testing):

python -m angelone_mcp.server

It speaks MCP over stdio, so it's meant to be launched by an MCP client, not

run interactively.

Claude Desktop / Claude Code config

Add to your MCP client's config (e.g. `claude_desktop_config.json`):

{
  "mcpServers": {
    "angelone": {
      "command": "/absolute/path/to/angelone-mcp/.venv/bin/python",
      "args": ["-m", "angelone_mcp.server"],
      "cwd": "/absolute/path/to/angelone-mcp",
      "env": {
        "ANGELONE_API_KEY": "your_api_key",
        "ANGELONE_CLIENT_CODE": "your_client_code",
        "ANGELONE_PIN": "your_pin",
        "ANGELONE_TOTP_SECRET": "your_base32_totp_secret",
        "ANGELONE_HTTPS_PROXY": "http://user:pass@proxyhost:8080"
      }
    }
  }
}

Tools exposed

Session

`login`, `logout`, `get_profile`

Orders

`place_order`, `modify_order`, `cancel_order`, `get_order_book`,

`get_trade_book`, `get_individual_order_details`

Portfolio / funds

`get_positions`, `get_holdings`, `get_all_holdings`, `get_rms_limit`,

`convert_position`

GTT (Good Till Triggered) rules

`gtt_create_rule`, `gtt_modify_rule`, `gtt_cancel_rule`, `gtt_details`,

`gtt_list`

Market data

`get_ltp`, `get_market_quote`, `search_scrip`, `get_candle_data`,

`get_oi_data`, `get_option_greeks`, `get_gainers_losers`,

`get_put_call_ratio`, `get_oi_buildup`, `get_nse_intraday_data`,

`get_bse_intraday_data`

Margin & brokerage

`get_margin`, `estimate_charges`

How auth works

`AngelOneClient` logs in lazily on the first tool call using

`clientcode` + `pin` + a TOTP generated on the fly from

`ANGELONE_TOTP_SECRET` (via `pyotp`). It caches the resulting `jwtToken`,

`refreshToken`, and `feedToken` in memory for the life of the process. If any

call comes back with a 401/403 or a `TokenException`, it transparently

re-logs-in once and retries — you don't need to call `login` yourself unless

you want to force a fresh session.

Sessions issued by SmartAPI are valid until midnight IST regardless of

activity, so a long-running server may still need a fresh login the next day

— the auto-retry logic handles that automatically on the next call.

Session persistence across restarts

A successful login is also cached to a file on disk, so a fresh server

process doesn't need a fresh TOTP-based login every time it starts (handy

since TOTP requires the code to be freshly generated — restarting the server

several times in a row otherwise means several real logins in a row).

On startup, before serving any tool calls, the server calls

`AngelOneClient.restore_session()`, which:

1. Looks for a previously saved session file. If there isn't one, it does

nothing further — the client stays in its normal lazy mode and logs in on

the first tool call, same as before this feature existed.

2. If a saved session is found, it loads the cached tokens and verifies them

with a real `getProfile` call.

3. If that verification succeeds, the restored session is used as-is — no

fresh login needed.

4. If it fails for any reason (expired token, revoked session, corrupt file,

etc.), the cached tokens are discarded and a normal fresh login runs

instead.

Every successful login (fresh or via the automatic 401/403 retry described

above) re-saves the session file, so it stays current across the whole time

the server runs, not just at startup. `logout` deletes the file.

The session file holds a live access token — not your PIN or TOTP secret,

but enough to call the API as you until it expires. It's written with

owner-only file permissions where the OS supports it; treat it as sensitive

the same way you'd treat any cached login session.

Rate limiting

`AngelOneClient` paces every outgoing call against

SmartAPI's documented per-endpoint rate limits

— login and most portfolio reads at 1 request/sec, `getProfile` at 3/sec,

quotes/GTT/order-detail lookups at 10/sec, order placement at 20/sec, and so

on. Limits are per SmartAPI endpoint, not global, so calling different tools

back-to-back is never slowed down by this — only a *repeat* call to the same

endpoint made faster than SmartAPI's own limit allows gets held back, which

you'd want anyway.

If SmartAPI reports its own limit was hit regardless (HTTP 403/429, "Access

denied because of exceeding access rate"), the call backs off and retries a

few times with increasing delay before giving up — and that response no

longer gets misread as an expired session and doesn't trigger a spurious

extra login the way it used to.

This applies to every tool automatically; there's nothing to configure to

get it. To turn client-side pacing off entirely (SmartAPI still enforces its

own limits server-side either way — this only controls whether the client

tries to stay under them proactively):

Testing

pip install -e ".[test]"

# Offline: verifies the server registers the expected tools. No credentials
# or network access needed.
python -m pytest tests/test_tool_registration.py -v

# Offline: unit tests for session persistence (login state cached to disk,
# restored + verified via get_profile on restart, falls back to a fresh
# login when the cache is missing/invalid). Uses a fake HTTP layer - no
# credentials or network access needed.
python -m pytest tests/test_session_persistence.py -v

# Offline: unit tests for AngelOneClient's own rate limiting (pacing per
# ROUTE_MIN_INTERVAL, backoff/retry on a 403/429 rate-limit response, and
# that such a response is never misread as an expired session). Uses a fake
# HTTP layer - no credentials or network access needed.
python -m pytest tests/test_client_rate_limiting.py -v

# Live, read-only smoke test against your real account. Calls get_profile,
# get_order_book, get_holdings, search_scrip, get_ltp, etc. through the
# actual MCP server subprocess, plus a check that a session survives a
# restart of the server without calling the "login" tool again. Never calls
# place_order/modify_order/cancel_order/gtt_create_rule/gtt_modify_rule/
# gtt_cancel_rule/convert_position/logout - a SafeSession wrapper
# hard-asserts those are never invoked. On top of the server's own rate
# limiting (see "Rate limiting" above), the test itself also paces its tool
# calls and backs off/retries if the API reports one was hit anyway (see
# "Rate limiting in the live test" below) - belt and suspenders. Requires
# ANGELONE_API_KEY/ANGELONE_CLIENT_CODE/ANGELONE_PIN/ANGELONE_TOTP_SECRET
# to be set; skips automatically if they aren't.
python -m pytest tests/test_readonly_live.py -v -s
# or, for a plain-text report without pytest:
python tests/test_readonly_live.py

Rate limiting in the live test

The live test (`tests/test_readonly_live.py`) calls a real account against

the real SmartAPI. The server it drives already paces itself (see "Rate

limiting" above), but the test adds its own independent pacing on top -

useful because it also exercises things the server-side limiter doesn't see

by itself, like two separate server subprocesses (the session-persistence

check) hitting the same account back to back:

• A `RateLimiter` tracks the last time each MCP tool was called and, before

calling it again, waits out the rest of that endpoint's minimum interval

(1/req-per-second-limit, plus a ~20% safety margin). Distinct tools hit

distinct SmartAPI endpoints with independent limits, so this only ever

delays a *repeat* call to the same tool (e.g. `get_profile` being called

again by the second server spawn in the session-persistence check) - a

normal single pass through the suite, where every tool is called once or

twice, isn't slowed down by it in practice.

• If SmartAPI reports a rate limit was hit anyway (HTTP 403, "Access denied

because of exceeding access rate"), the test backs off and retries a

couple of times with increasing delay instead of failing outright.

• This governs the test suite's own request pace only - it has no effect on

how the MCP server behaves for a real MCP client (Claude, etc.); SmartAPI

still enforces its limits server-side either way.

Notes / limitations

• Order params (`price`, `quantity`, etc.) are passed as strings, matching

what SmartAPI's `placeOrder` expects.

• `get_margin` and `estimate_charges` take a list of position/order dicts —

see the SmartAPI docs for exact field names per instrument type

(https://smartapi.angelone.in/docs/Margin, .../Brokerage).

• Rate limits are enforced by Angel One per endpoint; see

https://smartapi.angelone.in/docs/RateLimit. This server does not do its

own client-side rate limiting.

• Not affiliated with or endorsed by Angel One / Angel Broking.