# Kite MCP Server

A Model Context Protocol (MCP) server for integrating with Zerodha Kite API. This server provides Claude with tools to interact with your Kite trading account.

## Features

- **Portfolio Management**: Get positions, holdings, and orders
- **Market Data**: Real-time quotes, LTP, and instrument data
- **Order Management**: Place, modify, and cancel orders
- **Account Info**: Profile, margins, and authentication status
- **Secure Authentication**: OAuth 2.0 flow with token persistence

## Prerequisites

1. **Zerodha Kite Connect App**: Create an app at [Kite Connect](https://kite.trade/)
2. **API Credentials**: Get your API Key and Secret
3. **Bun**: Latest version of Bun runtime

## Installation

1. Clone and install dependencies:

```bash
bun install
```

2. Set up environment variables:

```bash
# Edit .env with your API credentials
```

3. Configure your Kite Connect app with redirect URL:

```
http://localhost:50000/zerodha/auth/redirect
```

## Quick Start

### 1. Authenticate with Kite API

```bash
bun run auth
```

This will:

- Start a local OAuth server
- Open your browser to Kite login
- Save your access token securely

### 2. Start the MCP Server

```bash
bun start
```

### 3. Configure Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "kite": {
      "command": "bun",
      "args": ["run", "/path/to/kite-mcp/src/index.ts"]
    }
  }
}
```

## Available Tools

### Portfolio Tools

- `get_profile` - Get user profile information
- `get_positions` - Get current trading positions
- `get_holdings` - Get long-term holdings
- `get_margins` - Get account margins and funds

### Order Tools

- `get_orders` - Get today's orders
- `place_order` - Place a new trading order
- `cancel_order` - Cancel an existing order

### Market Data Tools

- `get_ltp` - Get Last Traded Price for instruments
- `get_quote` - Get detailed market quotes
- `get_instruments` - Get tradable instruments list

### Utility Tools

- `get_auth_status` - Check authentication status

## Project Structure

```
src/
├── config/
│   └── environment.ts          # Configuration management
├── auth/
│   ├── token-manager.ts        # Token storage and validation
│   └── oauth-server.ts         # OAuth flow handling
├── api/
│   └── kite-client.ts          # Kite API wrapper
├── mcp/
│   ├── server.ts               # MCP server implementation
│   └── tools/
│       └── index.ts            # MCP tools definitions
├── auth.ts                     # Authentication entry point
└── index.ts                    # MCP server entry point
```

## Development

### Build (Optional)

```bash
bun run build
```

### Development Mode

```bash
bun run dev          # Watch mode for MCP server
bun run dev:auth     # Watch mode for auth server
```

### Architecture

The project follows the Single Responsibility Principle:

- **ConfigManager**: Environment and configuration handling
- **TokenManager**: Token persistence and validation
- **OAuthServer**: OAuth 2.0 authentication flow
- **KiteClient**: Kite API wrapper with error handling
- **KiteMCPServer**: MCP protocol implementation
- **Tools**: Individual MCP tool implementations

## Environment Variables

```bash
API_KEY=your_kite_api_key        # Required: Kite Connect API Key
API_SECRET=your_kite_api_secret  # Required: Kite Connect API Secret
OAUTH_PORT=50000                 # Optional: OAuth server port (default: 50000)
```

## Security

- Tokens are stored locally in `access_token.json`
- OAuth flow uses secure redirect handling
- API credentials are never logged or exposed
- Tokens auto-expire for security

## Troubleshooting

### Authentication Issues

1. Verify API credentials in `.env`
2. Check redirect URL in Kite Connect app settings
3. Ensure OAuth port (50000) is available

### Token Expiry

- Kite tokens expire every ~6 hours
- Re-run `bun run auth` when expired
- Server will notify you of authentication status

### MCP Connection Issues

1. Verify Claude Desktop configuration
2. Check server is running: `bun start`
3. Look for errors in Claude Desktop logs

## Contributing

1. Fork the repository
2. Create a feature branch
3. Follow the existing code structure and patterns
4. Add appropriate error handling
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Disclaimer

This is an unofficial integration with Zerodha Kite API. Use at your own risk. Always verify trades and orders before execution.