sriejan/zerodha-trade-mcp

Zerodha Trading MCP

A Model Context Protocol (MCP) server that enables AI models to interact with the Zerodha trading platform. This project provides a set of tools for executing trades, viewing portfolio, and managing positions on Zerodha through a standardized interface.

Features

• 🔐 Secure authentication with Zerodha API
• 📊 View portfolio holdings
• 📈 Check open positions
• 💹 Place buy/sell orders
• 👤 Access user profile information
• 🤖 NEW: Automated paper trading with Background Agents
• 📱 NEW: Smart auto-trigger system for continuous monitoring

Prerequisites

• Node.js (v14 or higher)
• Zerodha Trading Account
• API credentials from Zerodha
• Git repository initialized

Installation

1. Clone the repository:

git clone https://github.com/shubhamprajapati7748/zerodha-trade-mcp.git
cd zerodha-trade-mcp

2. Install dependencies:

npm install

3. Create a .env file in the root directory with your Zerodha credentials:

KITE_API_KEY=your_api_key
KITE_SECRET_KEY=your_secret_key
REQUEST_TOKEN=your_request_token
ACCESS_TOKEN=your_access_token

Automated Trading Setup

Background Agents (Recommended)

1. Initialize Git repository (required):

   git init
   git config user.name "Your Name"
   git config user.email "your.email@example.com"
   git add .
   git commit -m "Initial commit"
   

2. Configure environment (.cursor/environment.json already created):

   • Auto-trading monitor
   • Market data stream
   • Continuous portfolio updates

3. Start Background Agent:

   • Press Ctrl+E in Cursor IDE
   • Submit prompt: "Monitor my ₹1 lakh paper trading portfolio continuously, execute light-risk scalping trades, analyze market data every 30 seconds, and provide updates until market close"

Smart Auto-Trigger System

node smart_auto_trigger.cjs

• Copies trading commands to clipboard every 45 seconds
• Audio and visual alerts
• Windows notifications
• Just paste (Ctrl+V) in Cursor chat

Browser-Based Monitor

Open auto_chat_trigger.html in your browser:

• 30-second interval reminders
• Auto-clipboard functionality
• Market hours detection
• Audio alerts

Claude Desktop MCP Configuration

To use this MCP server with Claude Desktop, you need to configure the mcp server details. Here's how to set it up:

1. Open claude_desktop_config.json in your project root
2. Add the following configuration:

{
  "mcpServers": {
    "tradeStocks": {
      "command": "/opt/homebrew/bin/bun",
      "args": [
        "/path/to/your/index.ts"
      ], 
      "env": {
        "KITE_API_KEY": "your_api_key",
        "KITE_SECRET_KEY": "your_secret_key",
        "REQUEST_TOKEN": "your_request_token",
        "ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Make sure to:

• Update the path to your index.ts file
• Replace the environment variables with your actual Zerodha credentials

Paper Trading Strategy

Light Risk Scalping Approach

• Starting Capital: ₹1,00,000 (paper money)
• Risk per Trade: Maximum 0.5%
• Target: 0.5-1% quick profits
• Strategy: High-frequency monitoring with tight stops
• Focus: Quality stocks (ICICI, TCS, ITC, etc.)

Current Positions Example

💰 Cash: ₹1,240
📊 ICICI BANK: 700 shares @ ₹1,426.8 (+₹700 profit)
🎯 Target: ₹1,435 | Stop: ₹1,420

Usage

The MCP server provides the following tools:

Get Profile

get-profile

Retrieves the user's profile information from Zerodha.

Buy Stock

buy-stock {stock: string, quantity: number}

Places a buy order for the specified stock and quantity.

Sell Stock

sell-stock {stock: string, quantity: number}

Places a sell order for the specified stock and quantity.

Show Portfolio

show-portfolio

Displays current holdings and their values.

Show Positions

show-positions

Shows all open positions with P&L information.

Files Structure

├── index.ts                 # Main MCP server
├── trade.ts                 # Trading functions
├── auto-trader.js           # Standalone auto-trader
├── simple_auto_trader.py    # Python auto-trader
├── smart_auto_trigger.cjs   # Smart reminder system
├── auto_chat_trigger.html   # Browser-based monitor
├── .cursor/
│   └── environment.json     # Background Agent config
├── cursor-mcp-config.json   # MCP configuration
└── README.md               # This file

Security

• All trading credentials are stored securely in environment variables
• Paper trading mode recommended for testing
• Real money trading requires careful risk management
• Background Agents run in isolated environments

Troubleshooting

Git Repository Required

git init
git config user.name "Your Name"
git config user.email "your.email@example.com"

ES Module Errors

Use .cjs extension for CommonJS modules or update package.json type setting.

MCP Connection Issues

Check cursor-mcp-config.json configuration and restart Cursor IDE.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

This software is for educational and testing purposes only. Trading involves risk of financial loss. The authors are not responsible for any financial losses incurred through the use of this software. Always test with paper trading before using real money.

Support

For issues and questions:

• Create an issue on GitHub
• Check the troubleshooting section
• Review the MCP documentation

Happy Trading! 📈💹