Zerodha Trading Bot - MCP Server

A Model Context Protocol (MCP) server that integrates with Zerodha APIs for automated trading. This server provides tools for authentication, market data retrieval, order placement, and portfolio management.

Features

OAuth Authentication: Secure authentication with Zerodha APIs
Market Data: Real-time quotes and instrument information
Trading Operations: Place, modify, and cancel orders
Portfolio Management: View holdings, positions, and margins
MCP Integration: Full Model Context Protocol compliance

Prerequisites

Node.js 18+
Zerodha API credentials (API Key and Secret)
Zerodha trading account

Setup

1. Install Dependencies

npm install

2. Configure Environment Variables

Copy the example environment file and configure your Zerodha credentials:

cp env.example .env

Edit .env with your Zerodha API credentials:

# Zerodha API Configuration
ZERODHA_API_KEY=your_api_key_here
ZERODHA_API_SECRET=your_api_secret_here
ZERODHA_REDIRECT_URI=http://localhost:3000/callback
ZERODHA_BASE_URL=https://api.kite.trade

# MCP Server Configuration
MCP_SERVER_PORT=3001
MCP_SERVER_HOST=localhost

# Trading Configuration
DEFAULT_QUANTITY=1
DEFAULT_ORDER_TYPE=MIS
DEFAULT_PRODUCT_TYPE=INTRADAY

3. Get Zerodha API Credentials

Log in to your Zerodha account
Go to API Console
Create a new application
Note down your API Key and Secret
Set the redirect URI to http://localhost:3000/callback

4. Authentication

Start the authentication server:

node src/auth-server.js

Visit http://localhost:3000 and follow the OAuth flow. After successful authentication, you'll receive an access token. Add it to your .env file:

ZERODHA_ACCESS_TOKEN=your_access_token_here

Usage

Start the MCP Server

npm start

Test the Setup

npm test

Available Tools

The MCP server provides the following tools:

Authentication

get_login_url: Get OAuth login URL
authenticate: Authenticate with request token
validate_token: Check if access token is valid

Market Data

get_quote: Get live quotes for symbols
get_instruments: Get instrument information

Portfolio

get_user_profile: Get user profile
get_holdings: Get current holdings
get_positions: Get current positions
get_margins: Get margin information

Trading

place_order: Place trading orders
get_order_history: Get order history
cancel_order: Cancel existing orders

Example Usage

Place a Market Order

// Example order parameters
const orderParams = {
  tradingsymbol: "RELIANCE",
  exchange: "NSE",
  transaction_type: "BUY",
  quantity: 1,
  product: "MIS",
  order_type: "MARKET"
};

Get Live Quotes

// Get quotes for multiple symbols
const symbols = "NSE:RELIANCE,NSE:TCS,NSE:INFY";
const quotes = await zerodhaClient.getQuote(symbols);

File Structure

ZerodhaTradingBot/
├── src/
│   ├── server.js          # Main server entry point
│   ├── mcp-server.js      # MCP server implementation
│   ├── zerodha-client.js  # Zerodha API client
│   └── auth-server.js     # OAuth authentication server
├── test/
│   └── test.js           # Test suite
├── package.json
├── env.example
└── README.md

Security Considerations

Never commit your .env file to version control
Keep your API credentials secure
Use environment variables for sensitive data
Regularly rotate your access tokens

Error Handling

The server includes comprehensive error handling for:

Network connectivity issues
Invalid API credentials
Expired access tokens
Invalid order parameters
Rate limiting

Development

Running in Development Mode

npm run dev

Adding New Tools

To add new trading tools:

Add the method to ZerodhaClient class in src/zerodha-client.js
Add the tool handler in src/mcp-server.js
Update the tool definitions in the tools/list handler

Troubleshooting

Common Issues

Authentication Failed: Check your API credentials and redirect URI
Token Expired: Re-authenticate using the auth server
Order Rejected: Verify order parameters and account balance
Network Errors: Check internet connectivity and API endpoints

Debug Mode

Enable debug logging by setting:

DEBUG=true

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

Check the troubleshooting section
Review Zerodha API documentation
Open an issue on the repository

Disclaimer

This software is for educational and development purposes. Use at your own risk. Always test thoroughly in a paper trading environment before using with real money.