🚀 Zerodha MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the Zerodha trading platform. This server enables AI assistants to place stock orders, view holdings, and manage mutual fund investments through Zerodha's API.

TypeScript MCP SDK KiteConnect Bun

🎯 Features

Trading Tools

Place Stock Orders - Execute buy/sell orders on NSE and BSE
View Holdings - Get current stock portfolio holdings
Mutual Fund SIPs - View active Systematic Investment Plans
Mutual Fund Holdings - Check mutual fund portfolio (experimental)

Authentication

Zerodha Login - Secure OAuth-based authentication
Token Management - Automatic token storage and refresh
Session Handling - Persistent login sessions

Technical Features

TypeScript - Full type safety across the codebase
MCP Protocol - Standardized AI assistant integration
Error Handling - Comprehensive error management
Logging - Detailed operation logging

🏗️ Architecture

zerodha-mcp/ ├── config/ │ ├── KiteConfig.ts │ └── tokens.json ├── functions/ │ └── OrderRelated.ts ├── utils/ │ └── readWrite.ts ├── .env ├── bun.lock ├── main.ts └── package.json

🛠️ Tech Stack

TypeScript - Type-safe JavaScript
MCP SDK - Model Context Protocol implementation
KiteConnect - Zerodha's official trading API
Axios - HTTP client for API requests
Bun - Required JavaScript runtime

📦 Installation

Prerequisites

Bun - Required runtime
Zerodha trading account
Zerodha API credentials

1. Clone the Repository

git clone git@github.com:ManikLakhanpal/Zerodha-MCP.git cd zerodha-mcp

2. Install Dependencies

bun install

3. Environment Setup

Create a .env file in the root directory:

API_KEY=your_zerodha_api_key API_SECRET=your_zerodha_api_secret

4. Get Zerodha API Credentials

Log in to your Zerodha account
Go to Zerodha Developers
Create a new application
Copy your API Key and API Secret

🚀 Usage

Starting the MCP Server

bun main.ts

Using with Claude

This MCP server is designed to work with Claude AI assistants. Here's how to set it up:

1. Install Claude Desktop

First, download and install Claude Desktop for your operating system.

2. Configure Claude to Use MCP ⚙️

📱 Open Claude Desktop
🔧 Go to Settings → Developer Settings
📄 Click Open Config File to open claude_desktop_config.json in your default editor
✏️ Add the following configuration to the mcpServers section:

{ "mcpServers": { "kite": { "command": "/opt/homebrew/bin/bun", # Use `which bun` to get path "env": { "API_KEY": "your_zerodha_api_key", "API_SECRET": "your_zerodha_api_secret" }, "args": ["/path/to/your/zerodha-mcp/main.ts"] # Paste the absolute path to main.ts } } }

🔧 Important Notes:

🛠️ Replace /opt/homebrew/bin/bun with your Bun installation path (use which bun to find it)
📁 Replace /path/to/your/zerodha-mcp/main.ts with the actual path to your project's main.ts file
🔑 Replace your_zerodha_api_key and your_zerodha_api_secret with your actual Zerodha API credentials
🏷️ The server name "kite" can be changed to any name you prefer

3. Authentication Flow 🔐

🔑 First Login: Ask Claude to "login to Zerodha"
🌐 Get Login URL: Claude will provide a login URL
✅ Complete Login: Open the URL in your browser and complete Zerodha login
🔧 Set Tokens: Copy the request token from the URL and ask Claude to "set Zerodha tokens" with the token

4. Available Commands in Claude 💬

Once connected, you can ask Claude to:

🔐 "Login to Zerodha" - Get authentication URL
🔧 "Set Zerodha tokens with [request_token]" - Complete authentication
📈 "Place a buy order for 10 shares of RELIANCE on NSE" - Execute trades
📊 "Show my current holdings" - View portfolio
💰 "Get my mutual fund SIPs" - View SIP investments
🏦 "Check my mutual fund holdings" - View MF portfolio

5. Example Conversations 💭

You: 🔐 "Login to Zerodha" Claude: 🌐 [Provides login URL] You: 🔧 "Set Zerodha tokens with abc123xyz" Claude: ✅ [Confirms token setup] You: 📈 "Buy 5 shares of TCS on NSE" Claude: 💰 [Executes order and shows result] You: 📊 "What stocks do I currently hold?" Claude: 📋 [Shows your portfolio holdings]

Available Tools 🛠️

1. 🔐 Login to Zerodha

// Tool: login-to-zerodha // Returns a login URL for user authentication

2. 🔧 Set Authentication Tokens

// Tool: set-zerodha-tokens // Parameters: { request_token: string } // Sets access tokens after successful login

3. 📈 Place Stock Order

// Tool: place-stock-order // Parameters: { // variety: "regular" | "amo" | "co" | "auction" | "iceberg", // stock: string, // qty: number, // exchange: "NSE" | "BSE", // orderType: "BUY" | "SELL" // }

4. 📊 Get Holdings

// Tool: get-zerodha-holdings // Returns current stock portfolio holdings

5. 💰 Get Mutual Fund SIPs

// Tool: get-zerodha-mutual-fund-sips // Returns active Systematic Investment Plans

6. 🏦 Get Mutual Fund Holdings

// Tool: zerodha-mf-holdings // Returns mutual fund portfolio (experimental)

🔧 Configuration

🔐 Token Management

The server automatically manages authentication tokens:

📁 Tokens are stored in config/tokens.json
🔄 Automatic token refresh on session expiry
🛡️ Secure token handling with error recovery

⚡ API Limits

⏱️ Zerodha has rate limits on API calls
🛠️ The server includes built-in error handling
📝 Failed requests are logged with detailed error information

🔒 Security

🔐 Environment Variables - API credentials stored securely on your local machine
📝 Error Logging - No sensitive data in error messages

📊 API Reference

🏢 Zerodha API Integration

The server uses Zerodha's official KiteConnect API:

📈 Trading - Place orders, view holdings
💰 Mutual Funds - SIP management and holdings
🔐 Authentication - OAuth-based login flow

🤖 MCP Protocol

Implements the Model Context Protocol for AI assistant integration:

🛠️ Tool Definitions - Structured parameter schemas
🛡️ Error Handling - Graceful failure responses
🔒 Type Safety - Zod schema validation

🧪 Development

📁 Project Structure

src/ ├── main.ts # Server entry point ├── config/ │ └── KiteConfig.ts # Zerodha configuration ├── functions/ │ └── OrderRelated.ts # Trading functions └── utils/ └── readWrite.ts # File utilities

🛠️ Adding New Tools

📝 Define the tool in main.ts
⚙️ Implement the function in functions/
🛡️ Add proper error handling
📚 Update this README

🚨 Important Notes

⚠️ Trading Risks

💰 Real Money Trading - This server executes real trades
⏰ Market Hours - Orders only work during market hours
🛡️ Risk Management - Implement proper stop-loss mechanisms
🧪 Testing - Use paper trading for testing

🔧 API Limitations

⏱️ Rate Limits - Respect Zerodha's API rate limits
🕐 Market Hours - Some functions only work during trading hours
🏦 Account Type - Requires a Zerodha trading account

🔧 Troubleshooting

🚨 Common Issues

🔐 Authentication Errors

# Check if tokens are valid cat config/tokens.json # Re-authenticate if needed # Use login-to-zerodha tool

⚠️ API Errors

🔑 Verify API credentials in .env
🏦 Check Zerodha account status
⏰ Ensure market hours for trading functions

🌐 Network Issues

📡 Check internet connection
🏢 Verify Zerodha API status
📝 Review error logs for details

🤖 Claude MCP Connection Issues

🔍 Server Not Found: Ensure the working directory path is correct
🛠️ Command Not Found: Make sure bun is installed and in PATH
🔐 Authentication Failed: Check environment variables are set correctly
⏰ Token Expired: Re-authenticate using the login flow
🚫 Permission Denied: Ensure the project folder has proper read/write permissions

🤝 Contributing

🍴 Fork the repository
🌿 Create a feature branch (git checkout -b feature/new-tool)
⚙️ Implement your changes
🛡️ Add proper error handling
📚 Update documentation
📤 Submit a pull request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

⚠️ Disclaimer

This software is for educational and personal use only. Trading involves substantial risk of loss and is not suitable for all investors. The developers are not responsible for any financial losses incurred through the use of this software. 🛡️

🆘 Support

🐛 Issues - Report bugs via GitHub Issues
📚 Documentation - Check this README and code comments
🏢 Zerodha Support - Contact Zerodha for API-related issues

🙏 Acknowledgments

🏢 Zerodha - Trading platform and API
🤖 MCP SDK - Model Context Protocol implementation
🔒 TypeScript - Type safety and development experience

Made by Kshitij Banerjee 🔥

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI assistants to interact with the Zerodha trading platform for placing stock orders, viewing portfolio holdings, and managing mutual fund investments. Provides secure OAuth authentication and real-time trading capabilities through Zerodha's official API.

Related MCP Servers

Zerodha MCP Integration
aptro
-
security
A
license
-
quality
Integrates Zerodha's trading platform with Claude AI using the Multi-Cloud Plugin framework, allowing users to interact with their Zerodha trading account directly through Claude for stock trading and mutual fund operations.
Last updated -
43
MIT License
Zerodha Trading Bot
yogendhra9
A
security
F
license
A
quality
A Node.js-based trading bot that integrates with the Zerodha platform to provide automated stock trading operations through MCP tools including session management, buy/sell operations, and portfolio tracking.
Last updated -
6
Zerodha Trading Bot MCP
AmritanshuPrashar
-
security
F
license
-
quality
An automated trading bot that interfaces with Zerodha to execute stock trades, manage positions, and access market information through natural language commands.
Last updated -
1
DeFi Trading Agent MCP Server
edkdev
A
security
F
license
A
quality
Transforms AI assistants into autonomous crypto trading agents with real-time market analysis, portfolio management, and trade execution across 17+ blockchains.
Last updated -
32
42
15

View all related MCP servers