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```bash
npm install
### 2. Configure Environment Variables
Copy the example environment file and configure your Zerodha credentials:```bash
cp env.example .env
Edit .env with your Zerodha API credentials:```env
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:```bash
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:```env
ZERODHA_ACCESS_TOKEN=your_access_token_here
## Usage
### Start the MCP Server```bash
npm start
Test the Setup```bash
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```javascript
// Example order parameters
const orderParams = {
tradingsymbol: "RELIANCE",
exchange: "NSE",
transaction_type: "BUY",
quantity: 1,
product: "MIS",
order_type: "MARKET"
};
Get Live Quotes```javascript
// 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
.envfile 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```bash
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:```env
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.