zerodha-mcpserver

Zerodha Kite Connect MCP Server

This is a Cloudflare Worker that serves as an MCP (Model Context Protocol) server for interacting with the Zerodha Kite Connect API. It provides a comprehensive interface for trading and portfolio management through Zerodha.

Features

• Zerodha authentication and session management
• Portfolio management (holdings, positions)
• GTT (Good Till Triggered) orders
• Historical data retrieval
• MCP-compatible responses for seamless integration with Claude Desktop and other MCP clients

Setup

Prerequisites

• Zerodha Kite Connect API credentials (API Key and Secret)
• Cloudflare account

Deployment

1. Clone this repository

2. Install dependencies:

   npm install
   

3. Create your configuration file:

   cp wrangler.jsonc.example wrangler.jsonc
   

4. Configure your Zerodha API credentials in the wrangler.jsonc file:

   • Update the ZERODHA_API_KEY and ZERODHA_API_SECRET values
   • Note: This file is gitignored to prevent committing sensitive information

5. Create a KV namespace in Cloudflare:

   wrangler kv:namespace create ZERODHA_KV
   

6. Update the wrangler.jsonc file with the KV namespace ID

7. Add Node.js compatibility for crypto module:

   {
     "compatibility_date": "2023-05-18",
     "compatibility_flags": ["nodejs_compat"],
     ...
   }
   

8. Deploy the worker:

   npx wrangler deploy
   

Available Methods

Authentication

• getLoginUrl() - Generates a Zerodha login URL using the configured API key
• handleRedirect(requestToken) - Processes the request token after successful login
• rdhandle(requestToken) - Alternative endpoint for handling authentication redirects

Portfolio Management

• getHoldings() - Retrieves a list of equity holdings from Zerodha
• getPositions() - Retrieves current day and net positions

Orders

• getGTTOrders() - Retrieves Good Till Triggered orders

Market Data

• getHistoricalData(instrumentToken, interval, from, to, continuous, oi) - Retrieves historical candle data for a given instrument

Usage

With Claude Desktop or other MCP clients

Once deployed, you can add the worker as an MCP server in Claude Desktop:

1. Go to Settings > MCP Servers
2. Add a new server with your worker URL (e.g., https://zerodha-mcp.your-subdomain.workers.dev)
3. Claude will automatically discover the available methods

With JavaScript

// Example of using the MCP worker in JavaScript
const loginUrl = await zerodhaWorker.getLoginUrl();
console.log('Please login at:', loginUrl);

// Authentication flow
window.location.href = loginUrl;
// After redirect back with request_token in URL...
const urlParams = new URLSearchParams(window.location.search);
const requestToken = urlParams.get('request_token');

// Get holdings after authentication
const holdingsResponse = await zerodhaWorker.getHoldings();
const holdings = JSON.parse(holdingsResponse.content[0].text);
console.log('Your holdings:', holdings);

// Get historical data
const historicalData = await zerodhaWorker.getHistoricalData(
  '5633',           // instrument_token (NSE:INFY)
  'minute',         // interval
  '2023-01-01 09:15:00', // from
  '2023-01-01 09:30:00', // to
  false,            // continuous
  false             // oi
);
console.log('Historical data:', JSON.parse(historicalData.content[0].text));

Extending Functionality

To add more Zerodha API functionality:

1. Add new methods to the ZerodhaWorker class in src/index.js
2. Implement the desired Zerodha API calls using the Kite Connect API
3. Format responses according to the MCP specification (using the content array format)
4. Update the docs.json file to document the new methods
5. Deploy the updated worker

Response Format

All methods return responses in the MCP-compatible format:

{
  "content": [
    {
      "type": "text",
      "text": "{ ... data as JSON string ... }"
    }
  ]
}

Authentication Flow

1. User visits the login URL generated by getLoginUrl()
2. After successful login, Zerodha redirects to the callback URL with a request token
3. The /callback or /rdhandle endpoint processes the request token
4. The access token is obtained and stored in the KV namespace
5. Subsequent API calls use the stored access token

Security

• API keys and secrets are stored securely in Cloudflare environment variables
• Access tokens are stored in Cloudflare KV namespace
• The wrangler.jsonc file containing credentials is gitignored to prevent accidental exposure
• Only essential endpoints are exposed, minimizing attack surface

Development

To run the worker locally:

npx wrangler dev

To test the worker:

npx wrangler dev --test

API Documentation

For more information about the Zerodha Kite Connect API, refer to the official documentation:

• Kite Connect API Documentation
• Kite Connect API - Authentication
• Kite Connect API - Portfolio
• Kite Connect API - GTT Orders
• Kite Connect API - Historical Data

MCP Documentation

For more information about the Model Context Protocol (MCP), refer to:

• Model Context Protocol Documentation

License

MIT