# 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](https://developers.kite.trade/)
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 `.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

```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.