MCP 服务器

icici-mcp

Enables trading Indian stocks on ICICI Direct through natural conversation with any MCP-compatible AI assistant, featuring automated TOTP login and tools for portfolio monitoring, order placement, and market data.

README

<h1 align="center">icici-mcp</h1>

MCP server for ICICI Direct -- trade Indian stocks through natural conversation with any MCP-compatible AI assistant.

Why an MCP server instead of a Python library?

Traditional Breeze Connect wrappers require you to write Python code to trade. With icici-mcp, you just talk:

You:       "Buy 50 Reliance at market price"
Assistant: checks quote, verifies funds, asks for confirmation, places order

You:       "How's my portfolio doing?"
Assistant: fetches holdings, calculates P&L, summarizes gainers and losers

You:       "Show me the NIFTY option chain for next expiry"
Assistant: fetches option chain data with strikes, premiums, and OI

No code. No scripts. No terminal. Just conversation.

icici-mcp connects any MCP-compatible AI assistant directly to your ICICI Direct account with 14 trading tools, automated TOTP login, and auto-retry on expired tokens.

How it works

You (natural language) --> AI Assistant --> icici-mcp (MCP server) --> ICICI Direct Breeze API

Your AI assistant interprets your intent, maps stock names to symbols (e.g., "Infosys" to INFY), checks your funds, and executes trades -- all through the MCP protocol. The server handles authentication automatically, including daily token refresh via TOTP.

Features

14 tools for complete trading control:

Tool	Description
`icici_login`	Auto-authenticate with TOTP
`get_holdings`	Portfolio holdings with P&L
`get_demat_holdings`	All shares in your demat account
`get_positions`	Today's open positions
`get_orders`	Order history for a date range
`get_margins`	Available margins for trading
`get_funds`	Available funds in your account
`get_quote`	Live market quotes (equity and F&O)
`get_historical_data`	Historical OHLCV candle data
`get_option_chain`	Option chain quotes with strikes and premiums
`place_order`	Place buy/sell orders (market, limit, stop-loss)
`modify_order`	Modify pending orders
`cancel_order`	Cancel pending orders
`square_off`	Square off open positions

Key capabilities:

Fully automated login -- TOTP generated on the fly, no manual intervention
Auto-retry on stale tokens -- re-authenticates transparently if a token expires mid-session
Option chain data for F&O analysis
Supports equity (cash), futures, options, margin, and BTST orders

Compatible with

Works with any MCP-compatible client, including:

Client	Platform
Claude Desktop	macOS, Windows
Claude Code	Terminal (macOS, Linux, Windows)
Cursor	macOS, Windows, Linux
Windsurf	macOS, Windows, Linux
Continue	VS Code, JetBrains
Any MCP-compatible client	See MCP clients list

Quick Start

1. Install

pip install icici-mcp
playwright install chromium

Note: The playwright install chromium step is required once for automated TOTP login. It downloads a headless Chromium browser (~90MB) used to log in to ICICI Direct automatically.

2. Get your credentials

You need an ICICI Direct API app. From your app dashboard, note your API Key and API Secret.

You also need:

User ID -- your ICICI Direct client ID
Password -- your ICICI Direct login password
TOTP Secret (recommended) -- the base32 seed from setting up an external authenticator app for ICICI Direct 2FA. This enables fully automated login with no manual steps.

<details> <summary>How to get your TOTP secret</summary>

Log in to secure.icicidirect.com
Go to Profile > Security Settings > 2FA / TOTP Settings
Choose to set up an external authenticator app (Google Authenticator, Authy, etc.)
When the QR code appears, look for a "Can't scan? Copy this key" link or use a QR decoder to extract the secret
That key is your TOTP secret -- save it before completing setup
Enter the 6-digit code from your authenticator to finish

</details>

3. Configure your MCP client

Add this to your MCP client configuration. The config location depends on your client -- refer to your client's documentation for the exact path.

{
  "mcpServers": {
    "icici": {
      "command": "icici-mcp",
      "env": {
        "ICICI_API_KEY": "your-api-key",
        "ICICI_API_SECRET": "your-api-secret",
        "ICICI_USER_ID": "your-user-id",
        "ICICI_PASSWORD": "your-password",
        "ICICI_TOTP_SECRET": "your-totp-secret",
        "ICICI_SESSION_TOKEN": ""
      }
    }
  }
}

Restart your MCP client. You're ready to trade.

4. Try it out

Open a new chat and try:

"Show my portfolio holdings"
"What's Reliance trading at?"
"Buy 10 Infosys at market price"
"How much cash do I have available?"
"Cancel my last pending order"
"Show me NIFTY option chain for the nearest expiry"

The AI assistant understands stock names in plain English -- no need to use trading symbols.

Environment Variables

Variable	Required	Description
`ICICI_API_KEY`	Yes	ICICI Direct API key
`ICICI_API_SECRET`	Yes	ICICI Direct API secret
`ICICI_USER_ID`	Yes	ICICI Direct client ID
`ICICI_PASSWORD`	Yes	ICICI Direct login password
`ICICI_TOTP_SECRET`	No	TOTP base32 seed for auto-login. Without this, you must run `icici-mcp-login` manually each day or set `ICICI_SESSION_TOKEN`.
`ICICI_SESSION_TOKEN`	No	Manual session token from the ICICI Direct API login page. Use this if you cannot set up TOTP auto-login.

Manual Login

If you don't have a TOTP secret, you can log in manually each day:

Option 1: Use the CLI tool

export ICICI_API_KEY=your-api-key
export ICICI_API_SECRET=your-api-secret
export ICICI_USER_ID=your-user-id
export ICICI_PASSWORD=your-password
icici-mcp-login

This caches the session token for the rest of the day. The MCP server will use the cached token until it expires.

Option 2: Set ICICI_SESSION_TOKEN directly

Visit https://api.icicidirect.com/apiuser/login?api_key=YOUR_API_KEY
Complete the login flow manually
Copy the apisession value from the redirect URL
Set it as ICICI_SESSION_TOKEN in your MCP client config

Use Cases

Daily portfolio monitoring -- "Give me a summary of my portfolio with top gainers and losers"
Quick trades -- "Buy 50 Reliance" / "Sell all my Yes Bank"
F&O trading -- "Show me BANKNIFTY option chain" / "Buy 1 lot NIFTY 25000 CE"
Research + action -- "What's the 52-week high of HDFC Bank? Should I add more at current levels?"
Position management -- "Square off all my margin positions"
Scheduled reports -- Combine with MCP scheduled tasks to get a daily portfolio summary at 9am

Roadmap

[ ] Basket orders -- place multiple orders in one command
[ ] Mutual fund tools -- buy, redeem, check SIPs
[ ] IPO application tools
[ ] Portfolio analytics -- sector allocation, diversification score
[ ] Multi-account support

Have an idea? Open a feature request.

Development

git clone https://github.com/aranjan/icici-mcp.git
cd icici-mcp
python -m venv venv
source venv/bin/activate
pip install -e .

Security

Credentials are passed via environment variables -- never stored in code
Session tokens are cached locally at ~/.icici_direct_token.json and expire daily
The server runs locally on your machine -- no data is sent to third-party servers
All communication with ICICI Direct uses HTTPS

License

MIT