Content
# Zerodha Kite MCP Server
This project implements an MCP (Model Context Protocol) server that interacts with the Zerodha Kite API, allowing you to perform trading actions like buying and selling stocks, and fetching your holdings and positions.
## Prerequisites
1. **Node.js and npm/yarn:** Ensure you have Node.js installed. This project uses `typescript` and `esbuild` for building.
2. **Zerodha Kite Developer Account:** You need an account with Zerodha and access to their developer API.
## Setup Instructions
### 1. Create a Kite App
* Go to [https://developers.kite.trade/create](https://developers.kite.trade/create) and create a new app.
* During app creation, you can use any redirection URL (e.g., `https://localhost:3000/api/callback/userauth`). This URL is primarily used for the initial authentication flow.
* Note down the `API key` and `API secret` provided after app creation.
### 2. Configure API Keys in the Project
* Open the `index.ts` file.
* Replace `"your_api_key"` with your actual Kite App `API key`.
```typescript
const apiKey = "YOUR_ACTUAL_API_KEY"; // Replace with your API key
```
* **Important:** The `apiSecret` is needed for the initial access token generation. It's commented out in the `index.ts` file by default. You will need to uncomment it and add your `API secret` when generating the access token for the first time.
```typescript
// const apiSecret = "YOUR_ACTUAL_API_SECRET"; // Uncomment and replace for first-time token generation
```
### 3. Obtain an Access Token
The access token is required for the server to make authenticated calls to the Kite API. It needs to be generated once and can then be reused.
* **Step 3a: Get the Login URL**
* In `index.ts`, temporarily uncomment the `getLoginUrl` function:
```typescript
// async function getLoginUrl() {
// return kc.getLoginURL();
// }
```
* You'll also need to call this function. You can add a line like `console.log(await getLoginUrl());` at the end of the file or run it in a separate script.
* Run the modified `index.ts` (e.g., using `ts-node index.ts` or by building and running the JS output). This will print a login URL to your console.
* **Step 3b: Authorize and Get Request Token**
* Open the printed login URL in your browser.
* Log in with your Zerodha credentials and authorize the app.
* After successful authorization, you will be redirected to your specified `redirect_url`. The URL will contain a `request_token` parameter (e.g., `https://localhost:3000/api/callback/userauth?request_token=YOUR_REQUEST_TOKEN`).
* Copy this `request_token`.
* **Step 3c: Generate Access Token**
* In `index.ts`, uncomment the `getAccessToken` function and ensure your `apiSecret` is correctly set:
```typescript
// async function getAccessToken(requestToken: string) {
// const response = await kc.generateSession(requestToken, apiSecret);
// console.log(response.access_token);
// }
```
* Call this function with the `request_token` you obtained. For example, add `await getAccessToken("YOUR_REQUEST_TOKEN");` to the script or run it interactively.
* Run the script. This will print your `access_token` to the console.
* **Step 3d: Set the Access Token in `index.ts`**
* Copy the generated `access_token`.
* Paste it into the `access_token` variable in `index.ts`:
```typescript
const access_token = "YOUR_GENERATED_ACCESS_TOKEN"; // Replace with your access token
```
* **Security Note:** After generating the access token, you can (and should) comment out or remove the `getLoginUrl` and `getAccessToken` functions, and especially the `apiSecret` from `index.ts` to avoid accidental exposure. The `access_token` is long-lived.
### 4. Install Dependencies
Navigate to the project root directory in your terminal and run:
```bash
npm install
# or
yarn install
```
This will install `kiteconnect`, `@modelcontextprotocol/sdk`, `zod`, and other necessary dependencies.
### 5. Build the Project
The project uses TypeScript. You need to compile it to JavaScript. A common way is to use `esbuild` as suggested by the MCP server setup. If you have a `build` script in your `package.json` (e.g., `esbuild trader.ts --bundle --outfile=dist/trader.js --platform=node --format=esm`), run:
```bash
npm run build
# or
yarn build
```
This will typically create a `dist` directory with the compiled `trader.js` file. Make sure the output path matches the one you will use in the MCP server configuration (see below).
## Running the MCP Server
Once the setup is complete and the project is built, the MCP server can be started. The `trader.ts` (compiled to `dist/trader.js`) is the entry point for the MCP server.
The server listens for commands via standard input/output (stdio) when configured with an MCP client like Cursor.
## Configuring with Cursor
To use this trader bot as an MCP server in Cursor:
1. Go to Cursor settings (Cmd/Ctrl + ,).
2. Navigate to `Extensions` -> `MCP`.
3. Click on `Edit in settings.json` for `Model Context Protocol: Servers`.
4. Add the following configuration:
```json
{
"mcpServers": {
"trader": {
"command": "node",
"args": ["/path/to/your/Zerodha-MCP/dist/trader.js"] // Ensure this path is correct
}
}
}
```
**Important:** Replace `/path/to/your/Zerodha-MCP/dist/trader.js` with the absolute path to the compiled `trader.js` file on your system. For example, if your username is `user` and the project is in `Development/Zerodha-MCP`, the path would be `/Users/user/Development/Zerodha-MCP/dist/trader.js`.
## Available MCP Tools
The server exposes the following tools that can be called by an MCP client:
* ### `trader.add`
* **Description:** A simple tool to add two numbers.
* **Parameters:**
* `a` (number): The first number.
* `b` (number): The second number.
* **Returns:** The sum of `a` and `b`.
* ### `trader.sellStock`
* **Description:** Places a market sell order for a given stock.
* **Parameters:**
* `tradingsymbol` (string): The trading symbol of the stock (e.g., "INFY", "RELIANCE").
* `quantity` (number): The number of shares to sell.
* **Returns:** A confirmation message "Stock sold successfully" or an error if the transaction fails.
* **Note:** This uses `PRODUCT_CNC` (Cash and Carry, for delivery-based trades) and `EXCHANGE_NSE`. The order tag is automatically generated and incremented.
* ### `trader.buyStock`
* **Description:** Places a market buy order for a given stock.
* **Parameters:**
* `tradingsymbol` (string): The trading symbol of the stock.
* `quantity` (number): The number of shares to buy.
* **Returns:** A confirmation message "Stock bought successfully" or an error if the transaction fails.
* **Note:** This uses `PRODUCT_CNC` and `EXCHANGE_NSE`. The order tag is automatically generated and incremented.
* ### `trader.getPositions`
* **Description:** Fetches your current open positions.
* **Parameters:** None.
* **Returns:** A JSON string representing your current positions.
* ### `trader.getHoldings`
* **Description:** Fetches your current holdings (stocks in your demat account).
* **Parameters:** None.
* **Returns:** A JSON string representing your holdings.
## Project Structure Highlights
* `index.ts`: Contains the core Kite Connect API interaction logic, including setting API keys, access tokens, and functions for buying/selling stocks, and fetching profile, holdings, and positions. It also handles persisting an `orderTagCounter` in `counter.json` to ensure unique order tags.
* `trader.ts`: Sets up the MCP server using `@modelcontextprotocol/sdk`. It defines the tools exposed by the server and maps them to the functions in `index.ts`.
* `counter.json`: Automatically created in the same directory as `index.js` (or its compiled output) to store and persist the last used order tag number. This ensures that order tags are unique across server restarts.
## Development Notes
* **Order Tagging:** The system uses an incremental counter (`orderTagCounter` in `index.ts`, persisted in `counter.json`) to tag orders. This helps in identifying orders.
* **Error Handling:** Basic error handling is implemented (logging to console). You might want to expand this for more robust error reporting through the MCP.
* **Initial Setup:** The `init()` function in `index.ts` is called automatically when `index.ts` is imported. It loads the `orderTagCounter` and sets the Kite Connect access token.
