Kite MCP Server

https://github.com/zerodha/kite-mcp-server
Admin
The Kite MCP Server is a Model Context Protocol (MCP) server that provides AI assistants with secure...
Tokens:57,381
Snippets:456
Trust Score:8
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Session registry usage example in Go

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/session-registry.md

Shows how to initialize a session registry with a 24-hour duration, add a cleanup hook, start the cleanup routine, generate an internal session ID, validate it, get or create session data for an external ID, terminate a session, and stop the cleanup routine. The example uses the kc package from the kite-mcp-server project.

```go
package main

import (
	"context"
	"log/slog"
	"time"

	"github.com/zerodha/kite-mcp-server/kc"
)

func main() {
	logger := slog.New(slog.NewTextHandler(nil, nil))

	sm := kc.NewSessionRegistryWithDuration(24*time.Hour, logger)
	sm.AddCleanupHook(func(s *kc.MCPSession) {
		logger.Info("session cleaned up", "id", s.ID, "terminated", s.Terminated)
	})
	sm.StartCleanupRoutine(context.Background())

	// Internal ID
	id := sm.GenerateWithData("my-payload")
	if terminated, err := sm.Validate(id); err != nil || terminated {
		logger.Error("unexpected state", "err", err, "terminated", terminated)
	}

	// External (transport-provided) ID — created on demand
	_, isNew, err := sm.GetOrCreateSessionData("some-uuid-from-transport", func() any {
		return "fresh-data"
	})
	if err != nil {
		logger.Error("get-or-create failed", "error", err)
		return
	}
	logger.Info("created a new session for external ID", "isNew", isNew)

	sm.Terminate(id)         // fires cleanup hooks
	sm.StopCleanupRoutine()  // stop the background sweep
}
```

--------------------------------

### Usage Example

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-common.md

Example demonstrating how to use the handler factories and validation helpers.

```APIDOC
## Usage Example

### Description
Example of using `PaginatedToolHandler` and validation helpers in a custom tool.

### Code
```go
package main

import (
	"context"
	"log/slog"

	"github.com/mark3labs/mcp-go/mcp"
	"github.com/mark3labs/mcp-go/server"
	"github.com/zerodha/kite-mcp-server/kc"
	"github.com/zerodha/kite-mcp-server/mcp"
)

func myTool(manager *kc.Manager) server.ToolHandlerFunc {
	return mcp.PaginatedToolHandler(manager, "my_list", func(session *kc.KiteSessionData) ([]interface{}, error) {
		return session.Kite.Client.GetTrades() // any []T
	})
}

func build(srv *server.MCPServer, manager *kc.Manager, logger *slog.Logger) {
	srv.AddTool(
		mcp.NewTool("my_list", mcp.WithDescription("paginated list")),
		myTool(manager),
	)
	_ = logger
}

func main() {
	// Validation + coercion usage outside handlers
	args := map[string]interface{}{"order_id": "", "limit": 5}
	if err := mcp.ValidateRequired(args, "order_id"); err != nil {
		// ValidationError: parameter 'order_id': cannot be empty
		_ = context.Background()
		_ = mcp.SafeAssertInt(args["limit"], 0)
	}
}
```
```

--------------------------------

### RunServer method

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/app.md

Initializes and starts the server based on the configured mode. Blocks until shutdown, except for stdio sessions.

```go
// RunServer initializes and starts the server based on the configured mode
func (app *App) RunServer() error
```

--------------------------------

### Usage example for instruments manager

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/instruments-manager.md

This example shows how to create an instruments manager with a custom update configuration, load instruments, look up a symbol, force an update, and retrieve update statistics. It handles the ErrInstrumentNotFound error and prints the last update time and count.

```go
package main

import (
	"fmt"
	"log/slog"
	"time"

	"github.com/zerodha/kite-mcp-server/kc/instruments"
)

func main() {
	cfg := instruments.DefaultUpdateConfig()
	cfg.UpdateHour = 9  // refresh at 9:00 AM IST
	cfg.RetryAttempts = 5

	mgr, err := instruments.New(instruments.Config{
		UpdateConfig: cfg,
		Logger:       slog.New(slog.NewTextHandler(nil, nil)),
	})
	if err != nil {
		panic(err)
	}
	defer mgr.Shutdown()

	fmt.Println("loaded instruments:", mgr.Count())

	inst, err := mgr.GetByTradingsymbol("NSE", "INFY")
	if err == instruments.ErrInstrumentNotFound {
		fmt.Println("not found")
	} else {
		fmt.Printf("INFY token=%d segment=%s\n", inst.InstrumentToken, inst.Exchange)
	}

	// Force an immediate re-fetch
	if err := mgr.ForceUpdateInstruments(); err != nil {
		fmt.Println("update failed:", err)
	}

	stats := mgr.GetUpdateStats()
	fmt.Printf("last update: %v count: %d\n", stats.LastUpdateTime, stats.LastUpdateCount)
	_ = time.Now()
}
```

--------------------------------

### Mode-specific server startup methods

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/app.md

Internal methods to start the server in different modes: hybrid, stdio, SSE, and HTTP.

```go
func (app *App) startHybridServer(srv *http.Server, kcManager *kc.Manager, mcpServer *server.MCPServer, url string)  // app/app.go:323
func (app *App) startStdIOServer(srv *http.Server, kcManager *kc.Manager, mcpServer *server.MCPServer)              // app/app.go:345
func (app *App) startSSEServer(srv *http.Server, kcManager *kc.Manager, mcpServer *server.MCPServer, url string)     // app/app.go:361
func (app *App) startHTTPServer(srv *http.Server, kcManager *kc.Manager, mcpServer *server.MCPServer, url string)    // app/app.go:374
```

--------------------------------

### Build and run usage example

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/main.md

Shows how to build with version injection using justfile, run the binary with --version to print version and build info, and run with environment variables for API credentials and app mode.

```bash
# Build with version injection (justfile)
just build-version v1.2.3

# Run
./kite-mcp.bin --version
# Kite MCP Server v1.2.3
# Build: 2025-01-01 00:00:00 UTC - 0123456

# Run with env (see configuration.md)
KITE_API_KEY=xx KITE_API_SECRET=yy APP_MODE=stdio ./kite-mcp.bin
```

--------------------------------

### main function signature

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/main.md

Entry point of the server. Handles --version/-v flag, initializes logger, creates app, loads config, sets version, and runs the server. Exits with code 1 on config load or server start failure.

```go
func main()
```

--------------------------------

### Build and run the server

Source: https://github.com/zerodha/kite-mcp-server/blob/master/README.md

Build and run the server, or run directly with go run. The server starts and serves a status page at http://localhost:8080/.

```bash
# Build and run
go build -o kite-mcp-server
./kite-mcp-server

# Or run directly
go run main.go
```

--------------------------------

### Usage example with PaginatedToolHandler and validation

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-common.md

Complete example showing how to create a paginated tool handler, register it with the MCP server, and use ValidateRequired and SafeAssertInt outside handlers. The myTool function returns a handler that calls session.Kite.Client.GetTrades().

```go
package main

import (
	"context"
	"log/slog"

	"github.com/mark3labs/mcp-go/mcp"
	"github.com/mark3labs/mcp-go/server"
	"github.com/zerodha/kite-mcp-server/kc"
	"github.com/zerodha/kite-mcp-server/mcp"
)

func myTool(manager *kc.Manager) server.ToolHandlerFunc {
	return mcp.PaginatedToolHandler(manager, "my_list", func(session *kc.KiteSessionData) ([]interface{}, error) {
		return session.Kite.Client.GetTrades() // any []T
	})
}

func build(srv *server.MCPServer, manager *kc.Manager, logger *slog.Logger) {
	srv.AddTool(
		mcp.NewTool("my_list", mcp.WithDescription("paginated list")),
		myTool(manager),
	)
	_ = logger
}

func main() {
	// Validation + coercion usage outside handlers
	args := map[string]interface{}{"order_id": "", "limit": 5}
	if err := mcp.ValidateRequired(args, "order_id"); err != nil {
		// ValidationError: parameter 'order_id': cannot be empty
		_ = context.Background()
		_ = mcp.SafeAssertInt(args["limit"], 0)
	}
}
```

--------------------------------

### Run Just development commands

Source: https://github.com/zerodha/kite-mcp-server/blob/master/README.md

Use Just commands for common development tasks: build, run, test, lint, and coverage. Requires Just to be installed.

```bash
just build      # Build the project
just run        # Run the server
just test       # Run tests
just lint       # Format and lint code
just coverage   # Generate coverage report
```

--------------------------------

### Usage example for kc.New and session flow

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/kc-manager.md

Shows how to create a kc.Manager with API credentials from environment variables and a logger, then run a standalone login flow: generate a session, build a login URL, complete the session with a request token, and retrieve the session. Handles errors and logs the user profile when the session already exists.

```go
package main

import (
	"log/slog"
	"os"

	"github.com/zerodha/kite-mcp-server/kc"
)

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stderr, nil))

	manager, err := kc.New(kc.Config{
		APIKey:        os.Getenv("KITE_API_KEY"),
		APISecret:     os.Getenv("KITE_API_SECRET"),
		Logger:        logger,
		PublicBaseURL: "https://mcp.kite.trade",
	})
	if err != nil {
		logger.Error("failed to create manager", "error", err)
		os.Exit(1)
	}
	defer manager.Shutdown()

	// Standalone login flow
	sessionID := manager.GenerateSession()
	loginURL, err := manager.SessionLoginURL(sessionID)
	if err != nil {
		logger.Error("failed to build login URL", "error", err)
		return
	}
	logger.Info("ask the user to visit", "url", loginURL)

	// After Kite redirects back with ?request_token=...
	if err := manager.CompleteSession(sessionID, "kite-request-token"); err != nil {
		// ErrSessionNotFound or wrapped Kite error
		logger.Error("session completion failed", "error", err)
		return
	}

	data, isNew, err := manager.GetOrCreateSession(sessionID)
	if err != nil {
		logger.Error("session retrieval failed", "error", err)
		return
	}
	if !isNew {
		profile, err := data.Kite.Client.GetUserProfile()
		if err != nil {
			logger.Error("profile fetch failed", "error", err)
		}
		logger.Info("profile", "user", profile.UserName)
	}
}

```

--------------------------------

### Usage example for kite-mcp-server metrics

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/metrics.md

Shows how to initialize the metrics package, increment counters, track daily users, and expose metrics via the admin HTTP handler and Prometheus writer. Wrong secret paths return 404; non-GET requests to HTTPHandler return 405.

```go
package main

import (
	"bytes"
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/zerodha/kite-mcp-server/app/metrics"
)

func main() {
	m := metrics.New(metrics.Config{
		ServiceName:     "my-instance",
		AdminSecretPath: "s3cr3t",
		AutoCleanup:     true,
	})

	m.Increment("user_logins")          // plain counter
	m.IncrementDaily("tool_calls")      // daily counter: tool_calls_<today>
	m.TrackDailyUser("AB1234")

	fmt.Println("counter:", m.GetCounterValue("user_logins"))
	fmt.Println("users today:", m.GetTodayUserCount())

	// Admin endpoint behaves like http.HandlerFunc
	req := httptest.NewRequest(http.MethodGet, "/admin/s3cr3t/metrics", nil)
	rec := httptest.NewRecorder()
	m.AdminHTTPHandler()(rec, req)

	var buf bytes.Buffer
	m.WritePrometheus(&buf)
	fmt.Println(buf.String())

	m.Shutdown() // stop cleanup routine
}
```

--------------------------------

### Example JSON response for paginated tools

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-common.md

Example JSON shape returned by paginated tools when limit > 0, showing the data array and pagination metadata.

```json
{
  "data": [...],
  "pagination": { "from": 0, "limit": 10, "total": 123, "has_more": true, "returned": 10 }
}
```

--------------------------------

### Claude Desktop stdio Mode Build and Configuration

Source: https://github.com/zerodha/kite-mcp-server/blob/master/README.md

For self-hosted installations, first build the binary with 'go build -o kite-mcp-server', then configure Claude Desktop to use the full absolute path to the built binary. Add the JSON to ~/.config/Claude/claude_desktop_config.json. Requires APP_MODE=stdio and your Kite API credentials.

```bash
go build -o kite-mcp-server
```

```json
{
  "mcpServers": {
    "kite": {
      "command": "/full/path/to/your/kite-mcp-server",
      "env": {
        "APP_MODE": "stdio",
        "KITE_API_KEY": "your_api_key",
        "KITE_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

--------------------------------

### search_instruments parameters

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-tools-market.md

Example JSON payload for the search_instruments tool, specifying query, filter_on, and limit.

```json
{
  "name": "search_instruments",
  "arguments": { "query": "infy", "filter_on": "tradingsymbol", "limit": 10 }
}
```

--------------------------------

### Go usage example for session signing and verification

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/session-signer.md

Complete Go program demonstrating how to create a session signer, sign a session ID, verify it, and handle tampering errors. The default expiry is 5 minutes, but it can be tightened with SetSignatureExpiry. Verification errors can be checked with errors.Is against kc.ErrInvalidSignature, kc.ErrTamperedSession, kc.ErrInvalidFormat, or kc.ErrExpiredSignature.

```go
package main

import (
	"errors"
	"fmt"
	"time"

	"github.com/zerodha/kite-mcp-server/kc"
)

func main() {
	signer, err := kc.NewSessionSigner()
	if err != nil {
		panic(err)
	}

	// Default expiry is 5 minutes; tighten it if desired
	signer.SetSignatureExpiry(2 * time.Minute)

	signed := signer.SignSessionID("kitemcp-1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed")
	fmt.Println("signed:", signed)

	sessionID, err := signer.VerifySessionID(signed)
	if err != nil {
		panic(err)
	}
	fmt.Println("verified:", sessionID)

	// Error handling for tampering
	if _, err := signer.VerifySessionID("kitemcp-xxxx|1234.dG9rZW4="); err != nil {
		// kc.ErrInvalidSignature (base64), kc.ErrTamperedSession,
		// kc.ErrInvalidFormat, or kc.ErrExpiredSignature
		fmt.Println("verification failed:", err)
		if errors.Is(err, kc.ErrTamperedSession) {
			fmt.Println("session parameter was modified or forged")
		}
	}
}
```

--------------------------------

### New(cfg Config) (*Manager, error)

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/kc-manager.md

Creates a new kc Manager with the given configuration. It validates required fields, sets up the instruments manager, initializes a session signer, and starts the session cleanup and instruments update routines.

```APIDOC
## New(cfg Config) (*Manager, error)

### Description
Creates a new kc Manager with the given configuration. It validates required fields, sets up the instruments manager, initializes a session signer, and starts the session cleanup and instruments update routines.

### Method
Function

### Signature
`func New(cfg Config) (*Manager, error)`

### Parameters
#### Config
- **cfg.APIKey** (string) - Required - Kite Connect API key; empty → error `APIKey is required`
- **cfg.APISecret** (string) - Required - Kite Connect API secret; empty → error `APISecret is required`
- **cfg.Logger** (*slog.Logger) - Required - Logger; nil → error `logger is required`
- **cfg.PublicBaseURL** (string) - Optional - Public base URL for browser-facing auth links; trailing `/` trimmed
- **cfg.InstrumentsConfig** (*instruments.UpdateConfig) - Optional - Passed to the created instruments manager; defaults to `instruments.DefaultUpdateConfig()`
- **cfg.InstrumentsManager** (*instruments.Manager) - Optional - Reuse an existing instruments manager, skipping creation + initial load
- **cfg.SessionSigner** (*SessionSigner) - Optional - Custom HMAC signer; nil → a new signer with a random 256-bit key
- **cfg.Metrics** (*metrics.Manager) - Optional - Enables user-login and metric tracking

### Returns
- **(*Manager, error)** - A new Manager instance and an error if any.

### Errors
- `APIKey is required` - when APIKey is empty
- `APISecret is required` - when APISecret is empty
- `logger is required` - when Logger is nil
- `failed to create instruments manager: ...` - when instruments manager creation fails
- `failed to initialize Kite manager: ...` - when template parse fails
- `failed to initialize session signer: ...` - when session signer initialization fails

### Side Effects
Starts the session cleanup routine and the instruments update scheduler.
```

--------------------------------

### Go example: create signer with a shared key

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/session-signer.md

Constructs a session signer using a persisted 32-byte secret key, allowing signature verification across multiple server instances. Use this when you need to share signing across instances.

```go
signer := kc.NewSessionSignerWithKey([]byte("a-shared-32-byte-secret!!"))
```

--------------------------------

### New constructor function

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/instruments-manager.md

Constructs a new `Manager` with the given configuration. In production mode, it calls `UpdateInstruments()` immediately; failure returns an error wrapping `failed to load initial data`. Starts the scheduler goroutine when `EnableScheduler` is true.

```go
func New(cfg Config) (*Manager, error)                                     // kc/instruments/manager.go:121
```

--------------------------------

### GET /

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/endpoints.md

Status page endpoint that renders an HTML status page with server title, version, and mode. Returns 404 for any other path.

```APIDOC
## GET /

### Description
Status page endpoint that renders an HTML status page with server title, version, and mode. Returns 404 for any other path.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- Content-Type: text/html; charset=utf-8
- Body: Rendered status.html template with StatusPageData{Title: "Status", Version, Mode}

#### Response Example
(HTML content)

#### Error Responses
- 404 Not Found (text/plain; charset=utf-8) - Any path other than /
- 200 Kite MCP Server - Status template not available - If template is missing
- Error rendering status page - If template render fails
```

--------------------------------

### Place Regular Order (place_order)

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-tools-post.md

Example JSON payload for the 'place_order' tool. It places a regular LIMIT order to buy 1 share of INFY on NSE with CNC product, DAY validity, and a price of 1650.0. Requires an active session; otherwise, an error message is returned.

```json
{
  "name": "place_order",
  "arguments": {
    "variety": "regular",
    "exchange": "NSE",
    "tradingsymbol": "INFY",
    "transaction_type": "BUY",
    "quantity": 1,
    "product": "CNC",
    "order_type": "LIMIT",
    "price": 1650.0,
    "validity": "DAY",
    "tag": "ai-trade"
  }
}
```

--------------------------------

### Environment variables configuration (.env)

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/configuration.md

Example .env file contents. Required variables KITE_API_KEY and KITE_API_SECRET must be set; empty values cause a LoadConfig error. APP_MODE accepts stdio, http, sse, or hybrid; anything else triggers an invalid APP_MODE error at startup. LOG_LEVEL accepts debug, info, warn, or error; anything else falls back to info.

```env
KITE_API_KEY=your_api_key
KITE_API_SECRET=your_api_secret
APP_MODE=http
APP_PORT=8080
APP_HOST=localhost
PUBLIC_BASE_URL=https://mcp.kite.trade
EXCLUDED_TOOLS=
LOG_LEVEL=info
```

--------------------------------

### Place GTT Order (place_gtt_order)

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-tools-post.md

Example JSON payload for the 'place_gtt_order' tool. It places a single-trigger GTT SELL order for INFY on NSE with CNC product, trigger value 1500.0, limit price 1490.0, and quantity 1. Requires an active session; otherwise, an error message is returned.

```json
{
  "name": "place_gtt_order",
  "arguments": {
    "exchange": "NSE",
    "tradingsymbol": "INFY",
    "last_price": 1650.0,
    "transaction_type": "SELL",
    "product": "CNC",
    "trigger_type": "single",
    "trigger_value": 1500.0,
    "quantity": 1,
    "limit_price": 1490.0
  }
}
```

--------------------------------

### Parse and execute embedded templates with template.ParseFS

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/templates.md

Shows how to parse the embedded templates with template.ParseFS and execute the base template with data. The example serves a status page at the root route, setting the Content-Type header and passing a struct with Title, Version, and Mode fields to the template.

```go
package main

import (
	"html/template"
	"net/http"

	"github.com/zerodha/kite-mcp-server/kc/templates"
)

func main() {
	tmpl, err := template.ParseFS(templates.FS, "base.html", "status.html")
	if err != nil {
		panic(err)
	}

	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/html; charset=utf-8")
		_ = tmpl.ExecuteTemplate(w, "base", struct {
			Title   string
			Version string
			Mode    string
		}{Title: "Status", Version: "v1.0.0", Mode: "http"})
	})
	_ = http.ListenAndServe(":8080", nil)
}
```

--------------------------------

### Initialize environment with just init-env

Source: https://github.com/zerodha/kite-mcp-server/blob/master/README.md

Use the provided justfile to initialize the configuration.

```bash
just init-env
```

--------------------------------

### SSE Transport: GET /sse and POST /message

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/endpoints.md

SSE transport endpoints for MCP. GET /sse opens the SSE stream and emits endpoint events; POST /message receives JSON-RPC posts bound to the session.

```APIDOC
## SSE Transport: GET /sse and POST /message

### Description
SSE transport endpoints for MCP. GET /sse opens the SSE stream and emits endpoint events; POST /message receives JSON-RPC posts bound to the session.

### Method
GET and POST

### Endpoints
- GET /sse
- POST /message

### Response
#### Success Response (200)
- GET /sse: SSE stream with endpoint events
- POST /message: JSON-RPC response

### Notes
- MCP sessions created on this transport use external (plain UUID) session IDs.
- The session registry adopts them on first GetOrCreateSessionData call.
```

--------------------------------

### get_quotes parameters

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-tools-market.md

Example JSON payload for the get_quotes tool, specifying a list of instruments.

```json
{
  "name": "get_quotes",
  "arguments": { "instruments": ["NSE:INFY", "NSE:SBIN"] }
}
```

--------------------------------

### VerifyRedirectParams method

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/session-signer.md

Expects a string starting with 'session_id='; otherwise returns ErrInvalidFormat. Delegates to VerifySessionID after format check.

```go
func (s *SessionSigner) VerifyRedirectParams(redirectParams string) (string, error)  // kc/session_signing.go:159
```

--------------------------------

### get_historical_data parameters

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-tools-market.md

Example JSON payload for the get_historical_data tool, including instrument token, date range, interval, and oi flag.

```json
{
  "name": "get_historical_data",
  "arguments": {
    "instrument_token": 738561,
    "from_date": "2024-01-01 09:15:00",
    "to_date": "2024-01-31 15:30:00",
    "interval": "day",
    "oi": true
  }
}
```

--------------------------------

### Go: Initialize and run kite-mcp-server app

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/app.md

Use this snippet as the entry point for a kite-mcp-server application. It creates a slog logger, initializes the app, loads configuration, sets a version, and runs the server. The configuration error message is 'KITE_API_KEY or KITE_API_SECRET is missing'.

```go
package main

import (
	"log/slog"
	"os"

	"github.com/zerodha/kite-mcp-server/app"
)

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelInfo}))

	application := app.NewApp(logger)

	if err := application.LoadConfig(); err != nil {
		logger.Error("configuration error", "error", err)
		os.Exit(1)
	}

	application.SetVersion("v1.2.3")

	if err := application.RunServer(); err != nil {
		logger.Error("server failure", "error", err)
		os.Exit(1)
	}
}
```

--------------------------------

### GET /admin/<secret>/metrics

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/endpoints.md

Prometheus metrics endpoint, registered only when ADMIN_ENDPOINT_SECRET_PATH is set. Returns metrics in Prometheus text format.

```APIDOC
## GET /admin/<secret>/metrics

### Description
Prometheus metrics endpoint, registered only when ADMIN_ENDPOINT_SECRET_PATH is set. Returns metrics in Prometheus text format.

### Method
GET

### Endpoint
/admin/<ADMIN_ENDPOINT_SECRET_PATH>/metrics

### Response
#### Success Response (200)
- Content-Type: text/plain; version=0.0.4; charset=utf-8
- Body: Prometheus metrics

#### Error Responses
- 404 Not Found - If path does not exactly match /admin/<secret>/metrics or if secret is empty (endpoint disabled)
- 405 Method not allowed - If method is not GET
```

--------------------------------

### NewApp constructor

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/app.md

Creates a new application instance with the provided logger. Reads all configuration from environment variables and initializes internal components.

```go
// NewApp creates a new application instance with logger
func NewApp(logger *slog.Logger) *App
```

--------------------------------

### VerifyRedirectParams(redirectParams string) (string, error)

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/session-signer.md

Verifies a redirect parameter string that starts with `session_id=`. Delegates to VerifySessionID for the actual verification.

```APIDOC
## VerifyRedirectParams

### Description
Verifies a redirect parameter string that starts with `session_id=`. Delegates to VerifySessionID for the actual verification.

### Method
Method

### Signature
`func (s *SessionSigner) VerifyRedirectParams(redirectParams string) (string, error)`

### Parameters
- **redirectParams** (string) - Required - The redirect parameter string, expected to start with `session_id=`.

### Returns
- **string** - The bare session ID on success.
- **error** - Returns `ErrInvalidFormat` if the string does not start with `session_id=` or if the value is empty. Otherwise, returns the error from VerifySessionID.

### Example
```go
sessionID, err := signer.VerifyRedirectParams("session_id=abc.def")
if err != nil {
    // handle error
}
```
```

--------------------------------

### Clone the kite-mcp-server repository

Source: https://github.com/zerodha/kite-mcp-server/blob/master/README.md

Clone the repository and navigate into the project directory to begin self-hosting the server.

```bash
git clone https://github.com/zerodha/kite-mcp-server
cd kite-mcp-server
```

--------------------------------

### HTTPHandler method

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/metrics.md

Handler for the metrics endpoint. Non-GET requests get 405 Method Not Allowed; otherwise responds 200 with PrometheusContentType and the serialized metrics.

```go
func (m *Manager) HTTPHandler() http.HandlerFunc                           // metrics.go:320
```

--------------------------------

### Lookup instruments by tradingsymbol, ISIN, and underlying

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/instruments.md

Shows how to use the instruments.Manager to retrieve instrument data. It demonstrates GetByTradingsymbol, GetByISIN, and GetAllByUnderlying, including error handling with ErrInstrumentNotFound.

```go
package main

import (
	"errors"
	"fmt"

	"github.com/zerodha/kite-mcp-server/kc/instruments"
)

func lookup(mgr *instruments.Manager) {
	// By tradingsymbol
	infy, err := mgr.GetByTradingsymbol("NSE", "INFY")
	if err != nil {
		if errors.Is(err, instruments.ErrInstrumentNotFound) {
			fmt.Println("NSE:INFY not loaded")
			return
		}
		panic(err)
	}
	fmt.Printf("token=%d series=%s\n", infy.InstrumentToken, infy.Series)

	// By ISIN — all exchange listings
	byISIN, _ := mgr.GetByISIN(infy.ISIN)
	for _, i := range byISIN {
		fmt.Printf("  %s\n", i.ID)
	}

	// All NFO options on NIFTY (exchange NFO, name "NIFTY")
	fos, err := mgr.GetAllByUnderlying("NFO", "NIFTY")
	if err == nil {
		fmt.Printf("NIFTY F&O instruments: %d\n", len(fos))
	}
}
```

--------------------------------

### Run tests with Just or Go

Source: https://github.com/zerodha/kite-mcp-server/blob/master/README.md

Run tests with Just commands or directly with Go. Requires Go 1.23+ and GOEXPERIMENT=synctest for timing-dependent tests. The justfile automatically includes GOEXPERIMENT=synctest.

```bash
just test
```

```bash
just coverage
```

```bash
just test-race
```

```bash
CGO_ENABLED=0 GOEXPERIMENT=synctest go test -v ./...
```

--------------------------------

### GET /callback

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/endpoints.md

Kite OAuth callback endpoint that exchanges a request token for an access token and completes the session. Requires request_token and session_id query parameters.

```APIDOC
## GET /callback

### Description
Kite OAuth callback endpoint that exchanges a request token for an access token and completes the session. Requires request_token and session_id query parameters.

### Method
GET

### Endpoint
/callback

### Parameters
#### Query Parameters
- **request_token** (string) - Required - One-time token from Kite's redirect
- **session_id** (string) - Required - Signed session ID (signature verified)

### Response
#### Success Response (200)
- Body: login_success.html

#### Error Responses
- 400 missing MCP session_id or Kite request_token - If either parameter is missing
- 500 error completing Kite session - If session is invalid or token exchange fails
- 500 Internal server error: template not available - If success template is missing
```

--------------------------------

### GET /authorize

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/endpoints.md

Auth interstitial page that verifies a signed session ID and renders a page with a link to continue to Kite login. Requires a valid session_id query parameter.

```APIDOC
## GET /authorize

### Description
Auth interstitial page that verifies a signed session ID and renders a page with a link to continue to Kite login. Requires a valid session_id query parameter.

### Method
GET

### Endpoint
/authorize

### Parameters
#### Query Parameters
- **session_id** (string) - Required - HMAC-signed session ID produced by SessionAuthorizeURL or the login tool

### Response
#### Success Response (200)
- Body: authorize_interstitial.html containing the "Continue to Kite login" link

#### Error Responses
- 400 missing session_id - If session_id parameter is absent
- 400 invalid authorize session - If signature verification fails (tampered/expired)
- 400 session error - If session is terminated or not found
- 500 failed to generate Kite login URL - If login URL construction fails
- 500 internal server error - If template render fails
```

--------------------------------

### Enter Nix development shell

Source: https://github.com/zerodha/kite-mcp-server/blob/master/README.md

Enter the development shell using Nix, or use direnv to automatically load the environment when entering the project directory.

```bash
nix develop
```

```bash
direnv allow
```

--------------------------------

### Increment and IncrementBy methods

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/metrics.md

Atomically increments or creates a forever counter keyed by key. Increment is equivalent to IncrementBy(key, 1). Example counter used internally: "user_logins".

```go
func (m *Manager) Increment(key string)                                    // metrics.go:83
func (m *Manager) IncrementBy(key string, n int64)                         // metrics.go:88
```

--------------------------------

### LoadConfig method

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/app.md

Loads and validates the application configuration, applying defaults and returning an error if required API keys are missing.

```go
// LoadConfig loads and validates the application configuration
func (app *App) LoadConfig() error
```

--------------------------------

### Configure .env with Kite Connect credentials

Source: https://github.com/zerodha/kite-mcp-server/blob/master/README.md

Create a .env file with your Kite Connect credentials and server configuration. Required for self-hosting.

```env
KITE_API_KEY=your_api_key
KITE_API_SECRET=your_api_secret
APP_MODE=http
APP_PORT=8080
APP_HOST=localhost
PUBLIC_BASE_URL=http://localhost:8080
```

--------------------------------

### SessionLoginURL method

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/kc-manager.md

Gets/creates the session, signs the session ID with the SessionSigner, and returns the Kite login URL with &redirect_params=<url-escaped "session_id=<signed>"> appended to Client.GetLoginURL().

```go
func (m *Manager) SessionLoginURL(mcpSessionID string) (string, error)

```

--------------------------------

### QuotesTool struct and methods

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-tools-market.md

Defines the QuotesTool type and its Tool and Handler methods. The Handler uses the manager to call GetQuote with the instruments parameter. Validation errors include 'parameter 'instruments': is required' or 'cannot be empty', and API errors return 'Failed to get quotes'.

```go
type QuotesTool struct{}                                                        // market_tools.go:14
func (*QuotesTool) Tool() mcp.Tool                                              // market_tools.go:16
func (*QuotesTool) Handler(manager *kc.Manager) server.ToolHandlerFunc          // market_tools.go:29
```

--------------------------------

### App struct definition

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/app.md

Defines the main application structure with configuration, version, and internal dependencies.

```go
// App represents the main application structure
type App struct {
	Config         *Config
	Version        string
	startTime      time.Time
	kcManager      *kc.Manager
	statusTemplate *template.Template
	logger         *slog.Logger
	metrics        *metrics.Manager
}
```

--------------------------------

### Server construction helper function signatures

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/app.md

Declares the helper functions for building the public base URL and creating SSE and Streamable HTTP servers. buildPublicBaseURL returns PublicBaseURL (trailing / trimmed) if configured, otherwise derives scheme://host[:port] with specific rules. createSSEServer wraps the MCP server with server.NewSSEServer and createStreamableHTTPServer wraps it with server.NewStreamableHTTPServer, using the Kite session manager as the MCP session ID manager.

```go
func (app *App) buildPublicBaseURL() string                    // app/app.go:146
func (app *App) createSSEServer(mcpServer *server.MCPServer, url string) *server.SSEServer
func (app *App) createStreamableHTTPServer(mcpServer *server.MCPServer, kcManager *kc.Manager) *server.StreamableHTTPServer
```

--------------------------------

### LTPTool struct and methods

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/mcp-tools-market.md

Defines the LTPTool type and its Tool and Handler methods. The Handler calls GetLTP with the instruments parameter. An empty non-nil array yields 'At least one instrument must be specified', and API errors return 'Failed to get latest trading prices'.

```go
type LTPTool struct{}                                                            // market_tools.go:244
func (*LTPTool) Tool() mcp.Tool                                                  // market_tools.go:246
func (*LTPTool) Handler(manager *kc.Manager) server.ToolHandlerFunc              // market_tools.go:259
```

--------------------------------

### NewSessionSignerWithKey constructor

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/session-signer.md

Uses a caller-provided secret key. Panics with "secret key cannot be empty" if the key is empty. Useful for horizontally scaled deployments.

```go
func NewSessionSignerWithKey(secretKey []byte) *SessionSigner              // kc/session_signing.go:50
```

--------------------------------

### SetVersion method

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/app.md

Sets the server version string, which is also passed to the MCP server and rendered on the status page.

```go
// SetVersion sets the server version
func (app *App) SetVersion(version string)
```

--------------------------------

### New(cfg Config) (*Manager, error)

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/instruments-manager.md

Constructors for creating an instruments manager, including the primary New function and deprecated alternatives.

```APIDOC
## New(cfg Config) (*Manager, error)

### Description
Creates a new instruments manager. In production mode, it immediately calls UpdateInstruments() and starts the scheduler goroutine when EnableScheduler is true.

### Parameters
- **cfg.UpdateConfig** (*UpdateConfig) - Optional - Update/scheduler settings. Defaults to DefaultUpdateConfig() if nil.
- **cfg.Logger** (*slog.Logger) - Required - Logger for the manager.
- **cfg.TestData** (map[uint32]*Instrument) - Optional - If set, skips HTTP loading and uses test data.

### Returns
- (*Manager, error) - The new manager instance and an error if initial data loading fails.

### Errors
- Returns error with message "failed to load initial data: %w" if UpdateInstruments() fails in production mode.

### Deprecated Constructors

#### NewManager(logger *slog.Logger) *Manager
Deprecated: Use New(Config{Logger: logger}) instead. Does not load instruments automatically.

#### NewManagerWithConfig(config *UpdateConfig, logger *slog.Logger) *Manager
Deprecated: Use New(Config{UpdateConfig: config, Logger: logger}) instead. Does not load instruments automatically.
```

--------------------------------

### New(cfg Config) *Manager

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/metrics.md

Constructor for the metrics manager. It initializes the manager with the provided configuration, setting up Prometheus metrics, unique-user tracking, and optional admin endpoint.

```APIDOC
## New(cfg Config) *Manager

### Description
Creates a new metrics manager with the given configuration. The manager provides in-process Prometheus-format metrics, including atomic counters, per-day unique-user tracking, and an optional admin HTTP endpoint.

### Parameters
- `cfg.ServiceName` (string) - Optional - Label value added to every Prometheus metric as `service="..."`. Defaults to `DefaultServiceName` (`"kite-mcp"`).
- `cfg.AdminSecretPath` (string) - Optional - Secret appended to the admin metrics path; empty disables the admin endpoint. Defaults to `""`.
- `cfg.HistoricalDays` (int) - Optional - Number of past days whose unique-user counts appear in Prometheus output. Defaults to `DefaultHistoricalDays` (7).
- `cfg.CleanupRetentionDays` (int) - Optional - Daily-user records older than this are removed by cleanup. Defaults to `DefaultCleanupRetentionDays` (30).
- `cfg.AutoCleanup` (bool) - Optional - When true, starts the weekly cleanup goroutine. Defaults to `true`.

### Returns
- `*Manager` - Never `nil`. Note: `GetTodayUserCount`/daily metrics operate in UTC for keying but the cleanup routine sleeps until the next Saturday 3:00 AM UTC (`DefaultCleanupHour`/`DefaultCleanupDay`).
```

--------------------------------

### New function for kc Manager

Source: https://github.com/zerodha/kite-mcp-server/blob/master/_autodocs/api-reference/kc-manager.md

Signature for the New function that creates a kc Manager. It returns an error if required fields are missing, if instruments manager creation fails, if template parsing fails, or if session signer initialization fails. It also starts the session cleanup routine and instruments update scheduler.

```go
// New creates a new kc Manager with the given configuration
func New(cfg Config) (*Manager, error)
```
Tokens:
Raw