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