zap-kite-mcp

An MCP server that gives Claude read-only access to a Zerodha Kite Connect account and to Indian market data through one run_python tool. Claude writes a Python script against the zapkite library, the server runs it in an isolated subprocess and returns only what the script printed, so large data never enters the model's context. The same server hosts market watchers (Claude-authored conditions checked on a schedule without AI tokens, emailed when they become true) and a small web app where users log in to Zerodha and manage watchers.

How it fits together

Kite facts that shape the design: Kite sessions end around 06:00 IST every day and cannot be refreshed (users log in again from the web app); rate limits apply per API key, so one limiter fronts all users; Kite has no option-chain or greeks API, so the chain is derived from the daily instruments dump plus one batched quote call.

Related MCP server: Trade-MCP

Requirements

• Python 3.12 and uv.

• PostgreSQL 14 or newer.

• A Kite Connect app on the Connect plan (market data), with its redirect URL set to <web app origin>/api/broker/kite/callback.

• A Resend API key for login codes and alert emails (optional in development: codes are logged instead).

Run locally

cp .env.example .env            # fill KITE_API_KEY, KITE_API_SECRET, DATABASE_URL, secrets
uv sync
uv run zap-kite-mcp             # migrates the database, serves http://127.0.0.1:8019

cd web && cp .env.example .env  # same DATABASE_URL, SESSION_SECRET, CREDS_ENCRYPTION_KEY, Kite app
npm install && npm run dev      # http://127.0.0.1:3019

Set DEV_LOGIN_EMAIL and DEV_LOGIN_CODE in both .env files to sign in without email while developing. Open the web app, sign in, click "Log in to Zerodha". Add the MCP to claude.ai as a custom connector with URL http://127.0.0.1:8019/mcp (a public HTTPS URL in production); the connector runs the OAuth flow with the same email sign-in.

scripts/kite_login.py obtains a Kite access token without the web app and scripts/live_smoke.py exercises the library against the real API with it.

Deploy

Python server: deploy/ holds a hardened systemd unit, an nginx snippet (including the root-level OAuth discovery routes a path-scoped issuer needs), a one-time setup-uat.sh and update.sh. package.json wraps them: npm run deploy:setup once, then npm run deploy after every push to main; npm run status and npm run logs for operations.

Web app: import the repository into Vercel with root directory web/, add the variables from web/.env.example, and point the Kite app's redirect URL at https://<domain>/api/broker/kite/callback. Set ZAP_KITE_MCP_APP_URL on the Python server to the same domain.

Development

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest       # needs Postgres; ZAP_KITE_MCP_TEST_DATABASE_URL overrides the default

The Python suite runs the real server against an in-process fake Kite: OAuth login, scripts through the gateway, token expiry, watcher lifecycle and emails. npm run web:check typechecks, lints and tests the web app; its tests pin the crypto formats to vectors produced by the Python side.

Licence

MIT. See LICENSE.