# 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:
   ```json
   {
     "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

```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:

```json
{
  "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](https://kite.trade/docs/connect/v3/)
- [Kite Connect API - Authentication](https://kite.trade/docs/connect/v3/user/)
- [Kite Connect API - Portfolio](https://kite.trade/docs/connect/v3/portfolio/)
- [Kite Connect API - GTT Orders](https://kite.trade/docs/connect/v3/gtt/)
- [Kite Connect API - Historical Data](https://kite.trade/docs/connect/v3/historical/)

## MCP Documentation

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

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)

## License

MIT