# Zerodha Trading MCP Server

A MCP (Model Context Protocol) server built with FastMCP that gives an AI assistant **read-only** access to a Zerodha Kite account: holdings, positions, quotes, historical prices and rule-based price signals.

It cannot place, modify or cancel orders. That is enforced in code, not just stated: every Kite call goes through an allowlist, and anything else throws. See [GOVERNANCE.md](GOVERNANCE.md) for the controls, where your data goes, and the known gaps.

## Features

- Authentication with Zerodha
- Fetch stock prices from Zerodha
- Analyze price changes
- Get user portfolio
- Rule-based buy/sell signals from fixed thresholds (not advice)
- Find potential stocks to buy
- Fetch historical data

## Installation

1. Clone this repository
2. Install dependencies:

```bash
npm install
```

3. Configure Zerodha API credentials:
   - Create a `.env` file in the root directory
   - Add your Kite Connect app credentials (see `.env.example`):

```
API_KEY=your_kite_api_key
API_SECRET=your_kite_api_secret
```

The server never asks for your Zerodha password or PIN. You log in on Zerodha's own page, and the server only receives a short-lived request token.

## Running the Server

You can run the server in different ways:

### Using npm start

```bash
npm start
```

### Using FastMCP CLI for testing

```bash
npm run dev
```

This launches the FastMCP CLI for interactively testing the server in the terminal.

### Using MCP Inspector for visual testing

```bash
npm run inspect
```

This launches the MCP Inspector web UI for testing the server.

## Integrating with Cursor IDE

To integrate this MCP server with Cursor IDE:

1. Install Cursor IDE from https://cursor.sh/
2. Open Cursor settings 
3. Navigate to "AI" > "MCP Servers"
4. Add a new MCP server configuration:

```json
{
  "mcpServers": {
    "zerodha-trading-mcp": {
      "command": "node",
      "args": ["path/to/your/project/index.js"],
      "env": {
        "API_KEY": "your_zerodha_api_key",
        "API_SECRET": "your_zerodha_api_secret"
      }
    }
  }
}
```

Replace `path/to/your/project` with the actual path to your project directory and add your Zerodha API credentials.

5. Restart Cursor
6. When using Claude or another AI assistant in Cursor, you should now see your Zerodha trading tools available for the AI to use.

## Authentication Flow

Before using the tools that require authentication, you need to:

1. Call the `getLoginURL` tool to get the Zerodha login URL
2. Visit the URL and complete the login process
3. Copy the request token from the redirect URL
4. Call the `generateSession` tool with the request token
5. Now you can use all the other tools that require authentication

The access token is held in server memory. It is never returned to the AI assistant, and it expires daily.

## Available Tools

- `checkAuthStatus`: Check if the Zerodha API client is authenticated
- `getLoginURL`: Get the Zerodha login URL for authentication
- `generateSession`: Generate a session using the request token obtained after login
- `getProfile`: Get user profile information from Zerodha
- `getPortfolio`: Get user's stock portfolio (holdings) from Zerodha
- `getPositions`: Get user's current day trading positions from Zerodha
- `getStockPrice`: Get current market price for given stocks
- `getFavoriteStockPrices`: Get current market price for favorite/common stocks
- `analyzePriceChanges`: Analyze price changes for given stocks
- `analyzePortfolio`: HOLD/SELL/REDUCE flags per holding from fixed rules (profit target, stop loss, allocation cap)
- `findPotentialBuys`: Watchlist stocks that have dropped past the buy threshold

Every tool call is written to stderr as one JSON audit line (tool, arguments, outcome, duration), with the request token redacted.
- `getHistoricalData`: Get historical price data for a given instrument

## Customizing the Server

You can modify the following files to customize the server:

- `config.js`: Configure favorite stocks, trading parameters, and technical analysis parameters
- `zerodha.js`: Implement additional Zerodha API functions
- `index.js`: Add or modify tools

## Disclaimer

This server is provided for educational and informational purposes only. It is not intended to provide investment advice. The signals are fixed thresholds in `config.js`, not recommendations. Holdings and positions returned by the tools are sent to whichever AI model your MCP client uses. Always conduct your own research before making investment decisions.