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

1. Log in to your Zerodha account
2. Go to API Console
3. Create a new application
4. Note down your API Key and Secret
5. 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:

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

Troubleshooting

Common Issues

1. Authentication Failed: Check your API credentials and redirect URI
2. Token Expired: Re-authenticate using the auth server
3. Order Rejected: Verify order parameters and account balance
4. 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:

1. Check the troubleshooting section
2. Review Zerodha API documentation
3. 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.