# kite-mcp-server

A [Model Context Protocol](https://modelcontextprotocol.io) server for
[Zerodha Kite Connect](https://kite.trade). It gives any MCP client — Claude Desktop,
Claude Code, or any other compatible agent — direct, tool-based access to a user's
Kite account: portfolio, orders, margins, mutual funds, and (on a paid Connect plan)
live market data.

**Disclaimer:** This project is independently developed and is not affiliated with,
endorsed by, or sponsored by Zerodha. You are responsible for any action taken on
your trading account through this server. Order-placing and SIP tools interact with
real money — review the dry-run output of any tool before enabling live trading.

## Capabilities

Supports both Kite Connect app tiers. Tools that require live market data or
historical candles return a clear, actionable error on the free tier instead of a
generic API failure; every other tool works identically on both tiers.

**Available on the free ("Personal") tier:**

| Area | Tools |
|---|---|
| Profile & margins | `get_profile`, `get_margins` |
| Portfolio | `get_holdings`, `get_positions`, `get_auction_instruments` |
| Orders & reports | `get_orders`, `get_order_history`, `get_order_trades`, `get_trades` |
| Trading | `place_order`, `modify_order`, `cancel_order`, `convert_position` |
| GTT (standing stop-loss / target orders) | `get_gtts`, `get_gtt`, `place_gtt`, `modify_gtt`, `delete_gtt` |
| Margin calculators (pre-trade checks) | `calculate_order_margins`, `calculate_basket_margins` |
| Instrument lookup | `search_instruments` |
| Mutual funds | `get_mf_holdings`, `get_mf_orders`, `get_mf_sips`, `place_mf_order`, `cancel_mf_order`, `place_mf_sip`, `modify_mf_sip`, `cancel_mf_sip`, `search_mf_instruments` |

**Requires a paid Connect subscription with market data access:**

| Tool | Purpose |
|---|---|
| `get_quote`, `get_ohlc`, `get_ltp`, `get_trigger_range` | Live quotes and depth |
| `get_historical_data` | Historical OHLC candles |
| `watch_ticks` | Opens a WebSocket connection and returns a bounded snapshot (1–30s) of live ticks. MCP tools are request/response, so this trades continuous streaming for a short poll — call it again for a fresher snapshot. |

All tools that place, modify, or cancel an order, SIP, or position run in **dry-run
mode by default**. See [Trading safety](#trading-safety).

## Requirements

- Node.js 18 or later
- A Kite Connect app ([developers.kite.trade/apps](https://developers.kite.trade/apps)) — the free Personal tier is sufficient for most of this server's functionality

## Setup

1. **Create a Kite Connect app** at https://developers.kite.trade/apps. Note the API
   key and secret, and set a Redirect URL (it doesn't need to be a live server —
   `https://127.0.0.1` works for manual login).

2. **Clone and build:**

   ```bash
   git clone https://github.com/<your-username>/kite-mcp-server.git
   cd kite-mcp-server
   npm install
   npm run build
   ```

3. **Configure credentials** — copy `.env.example` to `.env` and fill in
   `KITE_API_KEY` and `KITE_API_SECRET`.

4. **Authenticate** (required once per trading day — Kite access tokens expire daily):

   ```bash
   npm run login
   ```

   This prints a login URL. Log in and complete two-factor authentication in your
   browser, then paste the resulting redirect URL (or just the `request_token` from
   it) back into the terminal. The access token is saved to `.kite-session.json`,
   which is excluded from version control.

5. **Register the server with your MCP client.** Example configuration for Claude
   Desktop (`claude_desktop_config.json`) or Claude Code (`settings.json`):

   ```json
   {
     "mcpServers": {
       "kite": {
         "command": "node",
         "args": ["/absolute/path/to/kite-mcp-server/dist/index.js"],
         "env": {
           "KITE_API_KEY": "your_api_key_here",
           "KITE_MCP_ENABLE_TRADING": "false"
         }
       }
     }
   }
   ```

## Trading safety

By default, `KITE_MCP_ENABLE_TRADING` is unset (equivalent to `false`), so every
order/SIP/position-mutating tool — `place_order`, `modify_order`, `cancel_order`,
`convert_position`, `place_gtt`, `modify_gtt`, `delete_gtt`, `place_mf_order`,
`cancel_mf_order`, `place_mf_sip`, `modify_mf_sip`, `cancel_mf_sip` — runs in dry-run
mode: it returns exactly what it would send to Kite without sending it. Set
`KITE_MCP_ENABLE_TRADING=true` once you've reviewed the dry-run output and want the
server to execute for real.

`calculate_order_margins` and `calculate_basket_margins` are always live and always
read-only, since they never place anything — use them to validate a trade before
enabling live trading.

There is no additional per-call confirmation beyond your MCP client's own tool-approval
UI. Treat enabling `KITE_MCP_ENABLE_TRADING` with the same caution as granting shell
access to your trading account.

## Daily token refresh

Kite's login flow requires a browser session and two-factor authentication, so it
cannot be fully automated without storing a user's 2FA secret — which this project
does not do. Run `npm run login` once per trading day before using the server. An
authentication error from any tool call is the first thing to check.

## Contributing

Issues and pull requests are welcome. Planned areas for contribution:

- Streaming tick data via MCP resources/notifications instead of the bounded
  `watch_ticks` poll
- Basket order execution
- Kite Alerts API integration

## License

MIT — see [LICENSE](LICENSE).