kite-connect-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. kite_connect_mcp-0.1.0/.env.example +95 -0
  2. kite_connect_mcp-0.1.0/.gitignore +42 -0
  3. kite_connect_mcp-0.1.0/CHANGELOG.md +45 -0
  4. kite_connect_mcp-0.1.0/LICENSE +21 -0
  5. kite_connect_mcp-0.1.0/PKG-INFO +187 -0
  6. kite_connect_mcp-0.1.0/README.md +153 -0
  7. kite_connect_mcp-0.1.0/deploy/caddy/Caddyfile.example +90 -0
  8. kite_connect_mcp-0.1.0/deploy/nginx/kite-connect-mcp.conf.example +112 -0
  9. kite_connect_mcp-0.1.0/deploy/systemd/kite-connect-mcp-logout.service +48 -0
  10. kite_connect_mcp-0.1.0/deploy/systemd/kite-connect-mcp-logout.timer +24 -0
  11. kite_connect_mcp-0.1.0/deploy/systemd/kite-connect-mcp.service +73 -0
  12. kite_connect_mcp-0.1.0/docs/CONFIGURATION.md +241 -0
  13. kite_connect_mcp-0.1.0/docs/DECISION.md +153 -0
  14. kite_connect_mcp-0.1.0/docs/KITE_SETUP.md +299 -0
  15. kite_connect_mcp-0.1.0/docs/SAFETY.md +396 -0
  16. kite_connect_mcp-0.1.0/docs/SELF_HOSTING.md +601 -0
  17. kite_connect_mcp-0.1.0/docs/TOOLS.md +1065 -0
  18. kite_connect_mcp-0.1.0/pyproject.toml +89 -0
  19. kite_connect_mcp-0.1.0/src/kite_connect_mcp/__init__.py +3 -0
  20. kite_connect_mcp-0.1.0/src/kite_connect_mcp/__main__.py +5 -0
  21. kite_connect_mcp-0.1.0/src/kite_connect_mcp/auth/__init__.py +0 -0
  22. kite_connect_mcp-0.1.0/src/kite_connect_mcp/auth/callback.py +147 -0
  23. kite_connect_mcp-0.1.0/src/kite_connect_mcp/auth/login.py +680 -0
  24. kite_connect_mcp-0.1.0/src/kite_connect_mcp/auth/loginstate.py +241 -0
  25. kite_connect_mcp-0.1.0/src/kite_connect_mcp/auth/tokenstore.py +257 -0
  26. kite_connect_mcp-0.1.0/src/kite_connect_mcp/cli.py +298 -0
  27. kite_connect_mcp-0.1.0/src/kite_connect_mcp/client/__init__.py +0 -0
  28. kite_connect_mcp-0.1.0/src/kite_connect_mcp/client/http.py +452 -0
  29. kite_connect_mcp-0.1.0/src/kite_connect_mcp/client/ratelimit.py +85 -0
  30. kite_connect_mcp-0.1.0/src/kite_connect_mcp/config.py +467 -0
  31. kite_connect_mcp-0.1.0/src/kite_connect_mcp/errors.py +144 -0
  32. kite_connect_mcp-0.1.0/src/kite_connect_mcp/instruments.py +973 -0
  33. kite_connect_mcp-0.1.0/src/kite_connect_mcp/postback.py +119 -0
  34. kite_connect_mcp-0.1.0/src/kite_connect_mcp/safety/__init__.py +0 -0
  35. kite_connect_mcp-0.1.0/src/kite_connect_mcp/safety/audit.py +120 -0
  36. kite_connect_mcp-0.1.0/src/kite_connect_mcp/safety/confirm.py +84 -0
  37. kite_connect_mcp-0.1.0/src/kite_connect_mcp/safety/pipeline.py +269 -0
  38. kite_connect_mcp-0.1.0/src/kite_connect_mcp/safety/policy.py +123 -0
  39. kite_connect_mcp-0.1.0/src/kite_connect_mcp/server.py +227 -0
  40. kite_connect_mcp-0.1.0/src/kite_connect_mcp/ticker/__init__.py +0 -0
  41. kite_connect_mcp-0.1.0/src/kite_connect_mcp/ticker/manager.py +840 -0
  42. kite_connect_mcp-0.1.0/src/kite_connect_mcp/ticker/parser.py +210 -0
  43. kite_connect_mcp-0.1.0/src/kite_connect_mcp/timeutil.py +45 -0
  44. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/__init__.py +5 -0
  45. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/_base.py +242 -0
  46. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/_orders_common.py +276 -0
  47. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/account.py +32 -0
  48. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/alerts.py +608 -0
  49. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/gtt.py +535 -0
  50. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/margins.py +314 -0
  51. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/market.py +481 -0
  52. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/mf.py +925 -0
  53. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/orders.py +381 -0
  54. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/portfolio.py +415 -0
  55. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/safety.py +69 -0
  56. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/session.py +277 -0
  57. kite_connect_mcp-0.1.0/src/kite_connect_mcp/tools/ticker.py +382 -0
  58. kite_connect_mcp-0.1.0/tests/conftest.py +237 -0
  59. kite_connect_mcp-0.1.0/tests/kite_login.py +108 -0
  60. kite_connect_mcp-0.1.0/tests/samples/alerts.py +18 -0
  61. kite_connect_mcp-0.1.0/tests/samples/gtt.py +16 -0
  62. kite_connect_mcp-0.1.0/tests/samples/mf.py +11 -0
  63. kite_connect_mcp-0.1.0/tests/samples/orders.py +15 -0
  64. kite_connect_mcp-0.1.0/tests/samples/portfolio.py +14 -0
  65. kite_connect_mcp-0.1.0/tests/test_alerts.py +766 -0
  66. kite_connect_mcp-0.1.0/tests/test_core_client.py +467 -0
  67. kite_connect_mcp-0.1.0/tests/test_docs.py +69 -0
  68. kite_connect_mcp-0.1.0/tests/test_gtt.py +731 -0
  69. kite_connect_mcp-0.1.0/tests/test_http_app.py +76 -0
  70. kite_connect_mcp-0.1.0/tests/test_instruments.py +966 -0
  71. kite_connect_mcp-0.1.0/tests/test_invariants.py +98 -0
  72. kite_connect_mcp-0.1.0/tests/test_login.py +1163 -0
  73. kite_connect_mcp-0.1.0/tests/test_margins.py +552 -0
  74. kite_connect_mcp-0.1.0/tests/test_market.py +713 -0
  75. kite_connect_mcp-0.1.0/tests/test_mf.py +887 -0
  76. kite_connect_mcp-0.1.0/tests/test_packaging.py +28 -0
  77. kite_connect_mcp-0.1.0/tests/test_portfolio.py +633 -0
  78. kite_connect_mcp-0.1.0/tests/test_postback.py +355 -0
  79. kite_connect_mcp-0.1.0/tests/test_safety_orders.py +405 -0
  80. kite_connect_mcp-0.1.0/tests/test_session_tools.py +420 -0
  81. kite_connect_mcp-0.1.0/tests/test_ticker.py +1414 -0
  82. kite_connect_mcp-0.1.0/tests/test_ticker_parser.py +397 -0
@@ -0,0 +1,95 @@
1
+ # kite-connect-mcp configuration. Copy to .env (mode 600) or put these in a systemd EnvironmentFile.
2
+ # Never commit a filled-in copy. Only the two credentials are active lines; every other setting is commented out and
3
+ # shows its default (or an example), so this file never overrides settings that come from elsewhere (e.g. a Docker
4
+ # image's ENV). Uncomment what you change. docs/CONFIGURATION.md explains every setting.
5
+
6
+ # --- Kite Connect app (https://developers.kite.trade) ----------------------------------------------------------
7
+ # Each secret can be given directly or as NAME_FILE=/path (a file with mode 600 holding only the value).
8
+ KITE_API_KEY=
9
+ # KITE_API_KEY_FILE=/etc/kite-connect-mcp/api_key
10
+ KITE_API_SECRET=
11
+ # KITE_API_SECRET_FILE=/etc/kite-connect-mcp/api_secret
12
+
13
+ # --- Session / token store -------------------------------------------------------------------------------------
14
+ # managed: this server owns the daily login (login link, /callback, token file, optional logout).
15
+ # external: another program writes the token file; this server only reads it (never writes, deletes or logs out).
16
+ # KITE_MCP_AUTH_MODE=managed
17
+ # The token file (JSON {access_token, login_date, logged_in_at, expires_at}, or a bare token). Default:
18
+ # $KITE_MCP_STATE_DIR/access_token.json
19
+ # KITE_TOKEN_FILE=
20
+ # A static token instead of the file (expiry unknown; Kite's answer decides). Usually leave unset.
21
+ # KITE_ACCESS_TOKEN=
22
+ # Refuse logins from any other Kite account (your user id, e.g. AB1234). Recommended in managed mode.
23
+ # KITE_MCP_ALLOWED_USER_ID=
24
+ # How long a login link stays usable (seconds; capped at the next 06:00 IST token reset).
25
+ # KITE_MCP_LOGIN_LINK_TTL_S=3600
26
+
27
+ # --- Local state ---------------------------------------------------------------------------------------------------
28
+ # Defaults: ~/.local/state/kite-connect-mcp (token, audit log, kill switch) and ~/.cache/kite-connect-mcp (instruments)
29
+ # KITE_MCP_STATE_DIR=
30
+ # KITE_MCP_CACHE_DIR=
31
+
32
+ # --- Transport ---------------------------------------------------------------------------------------------------
33
+ # stdio for desktop clients; http (Streamable HTTP at /mcp) for a server.
34
+ # KITE_MCP_TRANSPORT=stdio
35
+ # KITE_MCP_HOST=127.0.0.1
36
+ # KITE_MCP_PORT=8765
37
+ # Required for http: at least 32 random characters (openssl rand -hex 32). Clients send "Authorization: Bearer <it>".
38
+ # KITE_MCP_BEARER_TOKEN=
39
+ # KITE_MCP_BEARER_TOKEN_FILE=/etc/kite-connect-mcp/bearer_token
40
+ # The public https URL when behind a reverse proxy (example: https://kite.example.com). Used for Host checks.
41
+ # KITE_MCP_PUBLIC_URL=
42
+ # Extra Host header values to accept (comma-separated).
43
+ # KITE_MCP_ALLOWED_HOSTS=
44
+ # Path of the login callback; your Kite app's redirect URL must be <public url><this path>.
45
+ # KITE_MCP_CALLBACK_PATH=/callback
46
+ # Enable Kite order postbacks at this path (example: /postback); the postback URL in the developer console must match.
47
+ # KITE_MCP_POSTBACK_PATH=
48
+ # Only for a throwaway loopback test: serve HTTP without a bearer token.
49
+ # KITE_MCP_ALLOW_UNAUTHENTICATED_HTTP=false
50
+
51
+ # --- Safety ------------------------------------------------------------------------------------------------------
52
+ # true: every write tool is hidden and the HTTP client refuses write endpoints.
53
+ # KITE_MCP_READ_ONLY=false
54
+ # dry_run: writes can only be previewed. live: writes can be sent, after confirmation and every check.
55
+ # KITE_MCP_TRADING_MODE=dry_run
56
+ # token: a live write needs the confirmation_token from a dry run of the identical call.
57
+ # allowlist: writes whose every leg is in KITE_MCP_ALLOWED_INSTRUMENTS skip the token (everything else still needs it).
58
+ # KITE_MCP_LIVE_CONFIRMATION=token
59
+ # KITE_MCP_CONFIRMATION_TTL_S=300
60
+ # Caps on live writes (INR notional; quantity x price, or LTP / trigger based for MARKET / SL-M orders).
61
+ # KITE_MCP_MAX_ORDER_VALUE=10000
62
+ # KITE_MCP_MAX_DAILY_VALUE=50000
63
+ # KITE_MCP_MAX_ORDERS_PER_DAY=20
64
+ # KITE_MCP_MAX_QUANTITY=
65
+ # Allow-lists (comma-separated; unset or * = any). Instruments are EXCHANGE:TRADINGSYMBOL; mutual funds are
66
+ # MF:<ISIN>. Once an instrument list is set, anything not on it (funds included) is refused live.
67
+ # KITE_MCP_ALLOWED_INSTRUMENTS=NSE:INFY,NSE:TCS
68
+ # KITE_MCP_ALLOWED_EXCHANGES=NSE,BSE
69
+ # KITE_MCP_ALLOWED_PRODUCTS=CNC
70
+ # KITE_MCP_ALLOWED_VARIETIES=regular,amo
71
+ # KITE_MCP_ALLOWED_ORDER_TYPES=LIMIT
72
+ # KITE_MCP_ALLOWED_TRANSACTION_TYPES=BUY,SELL
73
+ # Mutual-fund order / SIP writes use legacy routes Kite no longer documents; off unless you opt in.
74
+ # KITE_MCP_ALLOW_MF_WRITES=false
75
+ # When this file exists every write is refused. Default: $KITE_MCP_STATE_DIR/KILL_SWITCH
76
+ # KITE_MCP_KILL_SWITCH_FILE=
77
+
78
+ # --- Tools -------------------------------------------------------------------------------------------------------
79
+ # Toolsets to expose (comma-separated or "all"): session,account,orders,gtt,alerts,portfolio,market,margins,mf,ticker,safety
80
+ # KITE_MCP_TOOLSETS=all
81
+ # Individual tools to hide (comma-separated names).
82
+ # KITE_MCP_EXCLUDED_TOOLS=
83
+
84
+ # --- WebSocket ticker ----------------------------------------------------------------------------------------------
85
+ # KITE_MCP_TICKER_ENABLED=true
86
+ # KITE_MCP_TICKER_MAX_SUBSCRIPTIONS=1000
87
+
88
+ # --- Endpoints (only change these for testing) ---------------------------------------------------------------------
89
+ # KITE_API_BASE_URL=https://api.kite.trade
90
+ # KITE_LOGIN_URL=https://kite.zerodha.com/connect/login
91
+ # KITE_TICKER_URL=wss://ws.kite.trade
92
+
93
+ # --- Misc --------------------------------------------------------------------------------------------------------
94
+ # KITE_MCP_HTTP_TIMEOUT_S=30
95
+ # KITE_MCP_LOG_LEVEL=INFO
@@ -0,0 +1,42 @@
1
+ # Secrets and credentials: never commit these
2
+ .env
3
+ .env.*
4
+ !.env.example
5
+ *.pem
6
+ *.key
7
+ *.p12
8
+ *.pfx
9
+ *token*.json
10
+ *token*.txt
11
+ access_token*
12
+ .secrets/
13
+ secrets/
14
+ # Local operator notes and PII patterns used by scripts/prepush_check.sh
15
+ .local/
16
+ .pii-patterns
17
+ .pii-secret-files
18
+
19
+ # Runtime state written by the server (token store, audit log, caches)
20
+ state/
21
+ cache/
22
+ *.jsonl
23
+ *.sqlite
24
+ *.sqlite3
25
+ *.db
26
+
27
+ # Python and tooling
28
+ .venv/
29
+ venv/
30
+ __pycache__/
31
+ *.py[cod]
32
+ *.egg-info/
33
+ build/
34
+ dist/
35
+ .pytest_cache/
36
+ .ruff_cache/
37
+ .mypy_cache/
38
+ .coverage
39
+ coverage.xml
40
+ htmlcov/
41
+ .claude/
42
+ .playwright-mcp/
@@ -0,0 +1,45 @@
1
+ # Changelog
2
+
3
+ All notable changes are listed here. Versions follow [semantic versioning](https://semver.org); while the version
4
+ is 0.x, minor releases may change tool arguments.
5
+
6
+ ## 0.1.0 (2026-11-04)
7
+
8
+ The first release: every Kite Connect v3 capability, behind a write-safety layer.
9
+
10
+ ### Tools (58 in 11 toolsets)
11
+
12
+ - **session**: session status (optionally verified with one read), the managed daily login (one-time links, a
13
+ state-checked callback, manual request-token completion) and a two-step logout.
14
+ - **account**: profile, funds and margins.
15
+ - **orders**: place, modify and cancel (regular, AMO, cover, iceberg and auction varieties, market protection,
16
+ autoslice), the order book, order history, trades.
17
+ - **gtt**: single and two-leg (OCO) GTTs: list, get, place, modify, delete.
18
+ - **alerts**: simple and alert-triggers-order alerts: list, get, history, create, modify, delete.
19
+ - **portfolio**: holdings and positions with summaries, auctions, position conversion, CDSL holdings authorisation.
20
+ - **market**: full quotes, OHLC, LTP, historical candles for every interval with continuous and OI data (long ranges
21
+ split automatically), and instrument search over the daily dump, cached in SQLite.
22
+ - **margins**: order margins, basket margins, and charges (the virtual contract note).
23
+ - **mf**: holdings, orders, SIPs and fund search; order and SIP writes on Kite's legacy routes, opt-in.
24
+ - **ticker**: the WebSocket stream as a managed connection with subscriptions, a latest-tick cache and order updates;
25
+ optional verified postbacks.
26
+ - **safety**: the safety settings and today's usage, the audit log, and a kill switch a tool can only engage.
27
+
28
+ ### Safety
29
+
30
+ - Every write is a dry run by default; live trading is off by default (`KITE_MCP_TRADING_MODE=dry_run`).
31
+ - A live write needs a single-use confirmation token bound to the exact request, or an explicitly allow-listed
32
+ instrument when you opt in.
33
+ - Per-order, daily value and daily count caps (read back from the audit log, so restarts never reset them);
34
+ modifications are held to the daily cap by their increase, and unknown outcomes count as if they happened.
35
+ - Allow-lists for instruments, exchanges, products, varieties, order types and sides; read-only mode; a kill switch.
36
+ - An append-only audit log, with each live intent fsynced before the request is sent; writes are never retried.
37
+ - An endpoint allow-list in the HTTP client, client-side rate limits under Kite's, credential scrubbing everywhere.
38
+
39
+ ### Running it
40
+
41
+ - stdio for desktop clients, Streamable HTTP behind a bearer token for servers, with Host-header checks.
42
+ - `managed` auth mode (this server owns the daily login) or `external` mode (it follows a token file another program
43
+ keeps, and never writes it or logs out).
44
+ - A two-stage Docker image, a hardened systemd unit, Caddy and nginx examples, and guides for the Kite developer
45
+ console (including the static IP live orders need), self-hosting and the safety model.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mayank Gupta
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,187 @@
1
+ Metadata-Version: 2.5
2
+ Name: kite-connect-mcp
3
+ Version: 0.1.0
4
+ Summary: Self-hostable MCP server for the full Zerodha Kite Connect v3 API, with dry-run-by-default order safety
5
+ Project-URL: Homepage, https://github.com/techfreakworm/kite-connect-mcp
6
+ Project-URL: Issues, https://github.com/techfreakworm/kite-connect-mcp/issues
7
+ Author: Mayank Gupta
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: kite,kiteconnect,mcp,model-context-protocol,trading,zerodha
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: Financial and Insurance Industry
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Office/Business :: Financial :: Investment
21
+ Requires-Python: >=3.11
22
+ Requires-Dist: httpx2>=2.16
23
+ Requires-Dist: mcp<3,>=2.3
24
+ Requires-Dist: pydantic>=2.10
25
+ Requires-Dist: starlette>=1.0
26
+ Requires-Dist: uvicorn>=0.30
27
+ Requires-Dist: websockets>=13
28
+ Provides-Extra: dev
29
+ Requires-Dist: mypy>=1.15; extra == 'dev'
30
+ Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
31
+ Requires-Dist: pytest>=8; extra == 'dev'
32
+ Requires-Dist: ruff>=0.15; extra == 'dev'
33
+ Description-Content-Type: text/markdown
34
+
35
+ # kite-connect-mcp
36
+
37
+ <!-- mcp-name: io.github.techfreakworm/kite-connect-mcp -->
38
+
39
+ [![CI](https://github.com/techfreakworm/kite-connect-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/techfreakworm/kite-connect-mcp/actions/workflows/release.yml)
40
+ [![PyPI](https://img.shields.io/pypi/v/kite-connect-mcp)](https://pypi.org/project/kite-connect-mcp/)
41
+ [![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)
42
+
43
+ A self-hostable [Model Context Protocol](https://modelcontextprotocol.io) server for the
44
+ [Zerodha Kite Connect v3 API](https://kite.trade/docs/connect/v3/). Run it on your own machine or server with
45
+ your own Kite Connect app, and let an AI assistant read your account, market data and orders. Every write is a
46
+ **dry run by default**.
47
+
48
+ > **Status: beta (0.x).** Every Kite Connect v3 capability is covered and tested offline against a fake Kite;
49
+ > expect rough edges against the real API and report them. Changes are listed in [CHANGELOG.md](CHANGELOG.md).
50
+ > This project is not affiliated with or endorsed by Zerodha.
51
+
52
+ ## Why another Kite MCP server?
53
+
54
+ Zerodha publishes an official server ([zerodha/kite-mcp-server](https://github.com/zerodha/kite-mcp-server)) and
55
+ hosts it at `mcp.kite.trade`. This project differs in three ways:
56
+
57
+ - **It covers the whole paid Kite Connect API.** That includes alerts, GTTs, order and basket margins, charges,
58
+ position conversion, holdings authorisation, auctions, mutual funds and the WebSocket ticker.
59
+ - **It's built for one person self-hosting.** The daily token is persisted and shared by every client you connect.
60
+ - **It has a safety layer for orders:** dry runs, two-step confirmation, value caps, allow-lists, a kill switch, an
61
+ audit log and rate limiting.
62
+
63
+ The full evaluation and reasoning are in [docs/DECISION.md](docs/DECISION.md).
64
+
65
+ ## What you need
66
+
67
+ - A Zerodha account, and a Kite Connect app from the [developer console](https://developers.kite.trade).
68
+ - **Connect (paid, ₹500/month per API key)** includes live quotes, the WebSocket and historical candles.
69
+ - **Personal (free)** covers orders, GTTs, alerts, portfolio and margins, but no market data. Market-data tools
70
+ return a clear "needs the paid plan" error.
71
+ - Python 3.11+ (or Docker).
72
+ - To place **live** orders: the order requests must come from a **static IP registered in the developer console**.
73
+ This is a SEBI/NSE rule, in force since April 2026. Reads work from any IP.
74
+
75
+ The developer-console steps are in [docs/KITE_SETUP.md](docs/KITE_SETUP.md): creating the app, the API key and
76
+ secret, the redirect and postback URLs, the subscription, and the static IP.
77
+
78
+ ## Quick start (local, stdio)
79
+
80
+ ```bash
81
+ # install
82
+ uv tool install kite-connect-mcp # or: pipx install kite-connect-mcp / pip install kite-connect-mcp
83
+ # or run without installing: uvx kite-connect-mcp --help
84
+ # or the image: docker pull ghcr.io/techfreakworm/kite-connect-mcp
85
+
86
+ # configure: credentials from env vars or files (mode 600)
87
+ export KITE_API_KEY=your_api_key
88
+ export KITE_API_SECRET_FILE=~/.config/kite-connect-mcp/api_secret
89
+
90
+ kite-connect-mcp check-config # validates settings, never prints credentials
91
+ kite-connect-mcp login --listen # prints the Kite login link and waits for the redirect (managed mode)
92
+ kite-connect-mcp status # session and safety status
93
+ ```
94
+
95
+ For `login --listen`, register `http://127.0.0.1:8765/callback` as your app's redirect URL. Every setting is listed in
96
+ [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
97
+
98
+ Add it to an MCP client, e.g. Claude Desktop (`claude_desktop_config.json`) or any client that launches stdio servers:
99
+
100
+ ```json
101
+ {
102
+ "mcpServers": {
103
+ "kite": {
104
+ "command": "kite-connect-mcp",
105
+ "args": ["serve"],
106
+ "env": { "KITE_API_KEY": "your_api_key", "KITE_API_SECRET_FILE": "/home/you/.config/kite-connect-mcp/api_secret" }
107
+ }
108
+ }
109
+ }
110
+ ```
111
+
112
+ To run it on a server over HTTP, see [docs/SELF_HOSTING.md](docs/SELF_HOSTING.md). It covers systemd and Docker,
113
+ a reverse proxy with TLS, bearer-token auth, and the login callback.
114
+
115
+ ## The safety model, in short
116
+
117
+ | Guard | Default |
118
+ |---|---|
119
+ | Every write tool takes `dry_run` | `true`: validate, run the checks, preview the exact request and Kite's margin calculation; send nothing |
120
+ | Live trading switch | off (`KITE_MCP_TRADING_MODE=dry_run`) |
121
+ | Confirmation | a live write needs the single-use `confirmation_token` from a dry run of the *identical* call (or, if you opt in, an explicitly allow-listed instrument) |
122
+ | Value caps | ₹10,000 per order, ₹50,000 per day, 20 live orders per day |
123
+ | Allow-lists | instruments, exchanges, products, varieties, order types, sides (all optional) |
124
+ | Read-only mode | `KITE_MCP_READ_ONLY=true` hides every write tool, and the HTTP client refuses write endpoints too |
125
+ | Kill switch | a file; a tool can switch it **on**, only a person can switch it off |
126
+ | Audit log | every dry run, refusal, live send and result, as JSON lines; the intent is fsynced *before* sending |
127
+ | Rate limits | kept under Kite's 1/s (quotes), 3/s (historical), 10/s (orders and the rest), 400 orders/min |
128
+ | Retries | reads back off and retry; **writes are never retried**. A timeout is reported as an unknown outcome: check the order book before trying again |
129
+
130
+ Details: [docs/SAFETY.md](docs/SAFETY.md).
131
+
132
+ ## Sessions and the daily login
133
+
134
+ Kite access tokens expire every day at about **06:00 IST**. A request token is single-use. Logging in again with the
135
+ same API key invalidates the previous access token. So one app should have exactly one program that owns the daily
136
+ login.
137
+
138
+ - **`managed` mode (default).** This server owns the login. The `login` tool (or `kite-connect-mcp login`) gives you
139
+ the link. Kite redirects to this server's `/callback`, which checks the one-time `state`, exchanges the
140
+ `request_token`, and stores the token with mode 600.
141
+ - **`external` mode.** Another program owns the login and writes a token file. This server only reads that file,
142
+ picks up the new token every morning without a restart, and never writes, deletes or logs out that token.
143
+
144
+ ## Tools
145
+
146
+ 58 tools in 11 toolsets (53 by default: the mutual-fund writes are opt-in). Tool names follow the official server
147
+ where one exists, so prompts carry over. Pick toolsets with `KITE_MCP_TOOLSETS` and hide single tools with
148
+ `KITE_MCP_EXCLUDED_TOOLS`; `kite-connect-mcp tools` lists what your configuration exposes.
149
+
150
+ | Toolset | Tools |
151
+ |---|---|
152
+ | session | `session_status`, `login`, `complete_login`, `logout` |
153
+ | account | `get_profile`, `get_margins` |
154
+ | orders | `place_order`, `modify_order`, `cancel_order`, `get_orders`, `get_order_history`, `get_trades`, `get_order_trades` |
155
+ | gtt | `get_gtts`, `get_gtt`, `place_gtt_order`, `modify_gtt_order`, `delete_gtt_order` |
156
+ | alerts | `get_alerts`, `get_alert`, `get_alert_history`, `create_alert` (simple and ATO), `modify_alert`, `delete_alerts` |
157
+ | portfolio | `get_holdings`, `get_positions`, `get_auctions`, `convert_position`, `authorise_holdings` |
158
+ | market | `get_quotes`, `get_ohlc`, `get_ltp`, `get_historical_data`, `search_instruments`, `get_instrument`, `get_instruments_status`, `refresh_instruments` |
159
+ | margins | `get_order_margins`, `get_basket_margins`, `get_order_charges` |
160
+ | mf | `get_mf_holdings`, `get_mf_orders`, `get_mf_sips`, `search_mf_instruments`; opt-in: `place_mf_order`, `cancel_mf_order`, `place_mf_sip`, `modify_mf_sip`, `cancel_mf_sip` |
161
+ | ticker | `ticker_subscribe`, `ticker_unsubscribe`, `ticker_get_ticks`, `ticker_status`, `ticker_order_updates`, `ticker_stop` |
162
+ | safety | `get_safety_status`, `get_audit_log`, `engage_kill_switch` |
163
+
164
+ Every argument of every tool is in [docs/TOOLS.md](docs/TOOLS.md).
165
+
166
+ ## Development
167
+
168
+ ```bash
169
+ git clone https://github.com/techfreakworm/kite-connect-mcp && cd kite-connect-mcp
170
+ python -m venv .venv && .venv/bin/pip install -e ".[dev]"
171
+ .venv/bin/pytest # never touches the network: Kite is faked in-process
172
+ .venv/bin/ruff check . && .venv/bin/ruff format --check .
173
+ ```
174
+
175
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
176
+
177
+ ## Disclaimer
178
+
179
+ Trading involves risk. This software can place real orders on a real brokerage account when you configure it to.
180
+ AI systems are unpredictable: keep the caps low, use dry runs, and review what you confirm. The software is provided
181
+ "as is", without warranty of any kind (see [LICENSE](LICENSE)). You are responsible for complying with Zerodha's
182
+ terms, SEBI's rules (including the static-IP and algo rules) and exchange data policies. Kite Connect data may not
183
+ be redistributed.
184
+
185
+ ## Licence
186
+
187
+ [MIT](LICENSE) © 2026 Mayank Gupta
@@ -0,0 +1,153 @@
1
+ # kite-connect-mcp
2
+
3
+ <!-- mcp-name: io.github.techfreakworm/kite-connect-mcp -->
4
+
5
+ [![CI](https://github.com/techfreakworm/kite-connect-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/techfreakworm/kite-connect-mcp/actions/workflows/release.yml)
6
+ [![PyPI](https://img.shields.io/pypi/v/kite-connect-mcp)](https://pypi.org/project/kite-connect-mcp/)
7
+ [![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue)](LICENSE)
8
+
9
+ A self-hostable [Model Context Protocol](https://modelcontextprotocol.io) server for the
10
+ [Zerodha Kite Connect v3 API](https://kite.trade/docs/connect/v3/). Run it on your own machine or server with
11
+ your own Kite Connect app, and let an AI assistant read your account, market data and orders. Every write is a
12
+ **dry run by default**.
13
+
14
+ > **Status: beta (0.x).** Every Kite Connect v3 capability is covered and tested offline against a fake Kite;
15
+ > expect rough edges against the real API and report them. Changes are listed in [CHANGELOG.md](CHANGELOG.md).
16
+ > This project is not affiliated with or endorsed by Zerodha.
17
+
18
+ ## Why another Kite MCP server?
19
+
20
+ Zerodha publishes an official server ([zerodha/kite-mcp-server](https://github.com/zerodha/kite-mcp-server)) and
21
+ hosts it at `mcp.kite.trade`. This project differs in three ways:
22
+
23
+ - **It covers the whole paid Kite Connect API.** That includes alerts, GTTs, order and basket margins, charges,
24
+ position conversion, holdings authorisation, auctions, mutual funds and the WebSocket ticker.
25
+ - **It's built for one person self-hosting.** The daily token is persisted and shared by every client you connect.
26
+ - **It has a safety layer for orders:** dry runs, two-step confirmation, value caps, allow-lists, a kill switch, an
27
+ audit log and rate limiting.
28
+
29
+ The full evaluation and reasoning are in [docs/DECISION.md](docs/DECISION.md).
30
+
31
+ ## What you need
32
+
33
+ - A Zerodha account, and a Kite Connect app from the [developer console](https://developers.kite.trade).
34
+ - **Connect (paid, ₹500/month per API key)** includes live quotes, the WebSocket and historical candles.
35
+ - **Personal (free)** covers orders, GTTs, alerts, portfolio and margins, but no market data. Market-data tools
36
+ return a clear "needs the paid plan" error.
37
+ - Python 3.11+ (or Docker).
38
+ - To place **live** orders: the order requests must come from a **static IP registered in the developer console**.
39
+ This is a SEBI/NSE rule, in force since April 2026. Reads work from any IP.
40
+
41
+ The developer-console steps are in [docs/KITE_SETUP.md](docs/KITE_SETUP.md): creating the app, the API key and
42
+ secret, the redirect and postback URLs, the subscription, and the static IP.
43
+
44
+ ## Quick start (local, stdio)
45
+
46
+ ```bash
47
+ # install
48
+ uv tool install kite-connect-mcp # or: pipx install kite-connect-mcp / pip install kite-connect-mcp
49
+ # or run without installing: uvx kite-connect-mcp --help
50
+ # or the image: docker pull ghcr.io/techfreakworm/kite-connect-mcp
51
+
52
+ # configure: credentials from env vars or files (mode 600)
53
+ export KITE_API_KEY=your_api_key
54
+ export KITE_API_SECRET_FILE=~/.config/kite-connect-mcp/api_secret
55
+
56
+ kite-connect-mcp check-config # validates settings, never prints credentials
57
+ kite-connect-mcp login --listen # prints the Kite login link and waits for the redirect (managed mode)
58
+ kite-connect-mcp status # session and safety status
59
+ ```
60
+
61
+ For `login --listen`, register `http://127.0.0.1:8765/callback` as your app's redirect URL. Every setting is listed in
62
+ [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
63
+
64
+ Add it to an MCP client, e.g. Claude Desktop (`claude_desktop_config.json`) or any client that launches stdio servers:
65
+
66
+ ```json
67
+ {
68
+ "mcpServers": {
69
+ "kite": {
70
+ "command": "kite-connect-mcp",
71
+ "args": ["serve"],
72
+ "env": { "KITE_API_KEY": "your_api_key", "KITE_API_SECRET_FILE": "/home/you/.config/kite-connect-mcp/api_secret" }
73
+ }
74
+ }
75
+ }
76
+ ```
77
+
78
+ To run it on a server over HTTP, see [docs/SELF_HOSTING.md](docs/SELF_HOSTING.md). It covers systemd and Docker,
79
+ a reverse proxy with TLS, bearer-token auth, and the login callback.
80
+
81
+ ## The safety model, in short
82
+
83
+ | Guard | Default |
84
+ |---|---|
85
+ | Every write tool takes `dry_run` | `true`: validate, run the checks, preview the exact request and Kite's margin calculation; send nothing |
86
+ | Live trading switch | off (`KITE_MCP_TRADING_MODE=dry_run`) |
87
+ | Confirmation | a live write needs the single-use `confirmation_token` from a dry run of the *identical* call (or, if you opt in, an explicitly allow-listed instrument) |
88
+ | Value caps | ₹10,000 per order, ₹50,000 per day, 20 live orders per day |
89
+ | Allow-lists | instruments, exchanges, products, varieties, order types, sides (all optional) |
90
+ | Read-only mode | `KITE_MCP_READ_ONLY=true` hides every write tool, and the HTTP client refuses write endpoints too |
91
+ | Kill switch | a file; a tool can switch it **on**, only a person can switch it off |
92
+ | Audit log | every dry run, refusal, live send and result, as JSON lines; the intent is fsynced *before* sending |
93
+ | Rate limits | kept under Kite's 1/s (quotes), 3/s (historical), 10/s (orders and the rest), 400 orders/min |
94
+ | Retries | reads back off and retry; **writes are never retried**. A timeout is reported as an unknown outcome: check the order book before trying again |
95
+
96
+ Details: [docs/SAFETY.md](docs/SAFETY.md).
97
+
98
+ ## Sessions and the daily login
99
+
100
+ Kite access tokens expire every day at about **06:00 IST**. A request token is single-use. Logging in again with the
101
+ same API key invalidates the previous access token. So one app should have exactly one program that owns the daily
102
+ login.
103
+
104
+ - **`managed` mode (default).** This server owns the login. The `login` tool (or `kite-connect-mcp login`) gives you
105
+ the link. Kite redirects to this server's `/callback`, which checks the one-time `state`, exchanges the
106
+ `request_token`, and stores the token with mode 600.
107
+ - **`external` mode.** Another program owns the login and writes a token file. This server only reads that file,
108
+ picks up the new token every morning without a restart, and never writes, deletes or logs out that token.
109
+
110
+ ## Tools
111
+
112
+ 58 tools in 11 toolsets (53 by default: the mutual-fund writes are opt-in). Tool names follow the official server
113
+ where one exists, so prompts carry over. Pick toolsets with `KITE_MCP_TOOLSETS` and hide single tools with
114
+ `KITE_MCP_EXCLUDED_TOOLS`; `kite-connect-mcp tools` lists what your configuration exposes.
115
+
116
+ | Toolset | Tools |
117
+ |---|---|
118
+ | session | `session_status`, `login`, `complete_login`, `logout` |
119
+ | account | `get_profile`, `get_margins` |
120
+ | orders | `place_order`, `modify_order`, `cancel_order`, `get_orders`, `get_order_history`, `get_trades`, `get_order_trades` |
121
+ | gtt | `get_gtts`, `get_gtt`, `place_gtt_order`, `modify_gtt_order`, `delete_gtt_order` |
122
+ | alerts | `get_alerts`, `get_alert`, `get_alert_history`, `create_alert` (simple and ATO), `modify_alert`, `delete_alerts` |
123
+ | portfolio | `get_holdings`, `get_positions`, `get_auctions`, `convert_position`, `authorise_holdings` |
124
+ | market | `get_quotes`, `get_ohlc`, `get_ltp`, `get_historical_data`, `search_instruments`, `get_instrument`, `get_instruments_status`, `refresh_instruments` |
125
+ | margins | `get_order_margins`, `get_basket_margins`, `get_order_charges` |
126
+ | mf | `get_mf_holdings`, `get_mf_orders`, `get_mf_sips`, `search_mf_instruments`; opt-in: `place_mf_order`, `cancel_mf_order`, `place_mf_sip`, `modify_mf_sip`, `cancel_mf_sip` |
127
+ | ticker | `ticker_subscribe`, `ticker_unsubscribe`, `ticker_get_ticks`, `ticker_status`, `ticker_order_updates`, `ticker_stop` |
128
+ | safety | `get_safety_status`, `get_audit_log`, `engage_kill_switch` |
129
+
130
+ Every argument of every tool is in [docs/TOOLS.md](docs/TOOLS.md).
131
+
132
+ ## Development
133
+
134
+ ```bash
135
+ git clone https://github.com/techfreakworm/kite-connect-mcp && cd kite-connect-mcp
136
+ python -m venv .venv && .venv/bin/pip install -e ".[dev]"
137
+ .venv/bin/pytest # never touches the network: Kite is faked in-process
138
+ .venv/bin/ruff check . && .venv/bin/ruff format --check .
139
+ ```
140
+
141
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
142
+
143
+ ## Disclaimer
144
+
145
+ Trading involves risk. This software can place real orders on a real brokerage account when you configure it to.
146
+ AI systems are unpredictable: keep the caps low, use dry runs, and review what you confirm. The software is provided
147
+ "as is", without warranty of any kind (see [LICENSE](LICENSE)). You are responsible for complying with Zerodha's
148
+ terms, SEBI's rules (including the static-IP and algo rules) and exchange data policies. Kite Connect data may not
149
+ be redistributed.
150
+
151
+ ## Licence
152
+
153
+ [MIT](LICENSE) © 2026 Mayank Gupta
@@ -0,0 +1,90 @@
1
+ # Caddy in front of kite-connect-mcp, with automatic HTTPS (Let's Encrypt or ZeroSSL).
2
+ # Walkthrough: docs/SELF_HOSTING.md.
3
+ #
4
+ # 1. Point the DNS record of kite.example.com at this server and open ports 80 and 443 in the firewall
5
+ # (Caddy needs both to obtain and renew the certificate).
6
+ # 2. Replace kite.example.com below, copy this file to /etc/caddy/Caddyfile, then: sudo systemctl reload caddy
7
+ # 3. In the kite-connect-mcp settings: KITE_MCP_PUBLIC_URL=https://kite.example.com
8
+ # (so the Host-header check accepts requests from this hostname).
9
+ #
10
+ # Only the paths listed here are forwarded; everything else gets a 404 from Caddy and never reaches the server.
11
+ # The server itself checks the bearer token on /mcp; /callback and /postback check their own inputs.
12
+ #
13
+ # --- global options ---
14
+ {
15
+ # The /callback URL carries one-time values (request_token, state). Without a `log` directive in the site block
16
+ # Caddy writes no access log, but its error log (stderr, so the journal) names the full request URI whenever the
17
+ # server is down. This redacts those two values there. If you already have a global options block, merge this in.
18
+ log {
19
+ format filter {
20
+ wrap json
21
+ request>uri query {
22
+ replace request_token REDACTED
23
+ replace state REDACTED
24
+ }
25
+ }
26
+ }
27
+ }
28
+
29
+ kite.example.com {
30
+ # an MCP request, a login redirect or a postback is a few kilobytes at most
31
+ request_body {
32
+ max_size 1MB
33
+ }
34
+
35
+ # --- MCP over Streamable HTTP, protected by the bearer token ---
36
+ @mcp path /mcp /mcp/*
37
+ handle @mcp {
38
+ reverse_proxy 127.0.0.1:8765 {
39
+ # replies can be streamed (Server-Sent Events): send them on as they come
40
+ flush_interval -1
41
+ }
42
+ }
43
+
44
+ # --- the Kite login redirect (the app's redirect URL is https://kite.example.com/callback) ---
45
+ @callback {
46
+ method GET
47
+ path /callback
48
+ }
49
+ handle @callback {
50
+ reverse_proxy 127.0.0.1:8765
51
+ }
52
+
53
+ # --- optional: Kite order postbacks. Needs KITE_MCP_POSTBACK_PATH=/postback on the server and
54
+ # https://kite.example.com/postback as the app's postback URL. Delete this block if you do not use them. ---
55
+ @postback {
56
+ method POST
57
+ path /postback
58
+ }
59
+ handle @postback {
60
+ reverse_proxy 127.0.0.1:8765
61
+ }
62
+
63
+ # --- optional: health check (the answer includes the version number). Delete this block unless something
64
+ # outside the server polls it. ---
65
+ @health {
66
+ method GET
67
+ path /health
68
+ }
69
+ handle @health {
70
+ reverse_proxy 127.0.0.1:8765
71
+ }
72
+
73
+ # everything else
74
+ handle {
75
+ respond "Not found" 404
76
+ }
77
+
78
+ # No access log, on purpose. If you want one, redact the same two values; add this block here:
79
+ #
80
+ # log {
81
+ # output file /var/log/caddy/kite-access.log
82
+ # format filter {
83
+ # wrap json
84
+ # request>uri query {
85
+ # replace request_token REDACTED
86
+ # replace state REDACTED
87
+ # }
88
+ # }
89
+ # }
90
+ }