README.mdโข2.67 kB
# ๐ KiteMCP โ Zerodha Trading via MCP
**KiteMCP** is a command-based Zerodha trading system built using the [KiteConnect API](https://github.com/zerodha/kiteconnectjs), [Bun](https://bun.sh), and the [Model Context Protocol (MCP)](https://modelcontextprotocol.dev). It allows real-time stock buy/sell operations through MCP command calls from a local server, currently integrated with Claude or any compatible tool interface.
---
## ๐ Features
- ๐ Buy and sell stocks programmatically via commands
- ๐ Modular MCP tool structure (`buy-stock`, `sell-stock`)
- ๐ Secure API key handling via `.env`
- โ
Schema validation using [Zod](https://zod.dev)
- โ๏ธ Fast runtime with Bun and TypeScript
- ๐งช Local test environment with log outputs
---
## ๐ง Setup Instructions
### 1. Clone the Repository
```bash
git clone https://github.com/your-username/zerodha-trade
cd zerodha-trade
```
### 2. Install Dependencies (using Bun)
```bash
bun install
```
### 3. Configure Environment Variables
Create a `.env` file in the root:
```env
KITE_API_KEY=your_api_key
KITE_API_SECRET=your_api_secret
ACCESS_TOKEN=your_access_token
```
### 4. Start the MCP Server
```bash
bun index.ts
```
---
### ๐ธ Screenshots
## Claude AI making transaction
<img src="assests/claudeAI.png" alt="MCP Command Demo" width="500"/>
## Zerodha server
<img src="assests/Screenshot 2025-07-18 153130.png" alt="MCP Command Demo" width="500"/>
## ๐ฅ Example Command Usage
Send the following JSON to the server via terminal or Claude:
```json
{
"id": "1",
"action": "call_tool",
"tool": "buy-stock",
"arguments": {
"symbol": "RELIANCE",
"exchange": "NSE",
"quantity": 10,
"price": 2800
}
}
```
---
## โ
Input Validation
All tool inputs are validated using **Zod** for:
- Required fields: `symbol`, `exchange`, `quantity`
- Type and range checks
- Custom error messages on invalid input
---
## ๐งช Example Output
```json
{
"status": "success",
"message": "Buy order placed for RELIANCE at โน2800"
}
```
---
## ๐ก๏ธ Security Notes
- Do **not** expose your `.env` file in production
- Add rate limiting and request authentication if going public
- Store order logs securely
---
## ๐ Future Enhancements
- ๐ Deploy on cloud with webhook interface
- ๐ Add portfolio view and PnL tracking
- ๐ Telegram/email alerts for order confirmations
- ๐ง Auto-trading with strategy modules
---
## ๐จโ๐ป Author
**Utkarsh Agarwal**
[GitHub](https://github.com/utkarshagar2121) โข [LinkedIn](https://linkedin.com/in/utkarsh-agarwal-1b359922b)
---
## ๐ License
MIT License ยฉ 2025 Utkarsh Agarwal