hityaasdfg/MCP_server

Zerodha MCP Integration

Seamlessly integrate Zerodha's trading platform with Claude AI using the Model Context Protocol (MCP). Trade stocks, manage mutual funds, and monitor your portfolio—all through natural conversation with Claude.

✨ Features

Stock Trading

• 📊 Real-time portfolio and position tracking
• 💰 Instant margin and balance checks
• 📈 Live market quotes and historical data
• 🎯 Quick order placement and management

Mutual Funds

• 🏦 Complete mutual fund portfolio overview
• 📅 SIP (Systematic Investment Plan) management
• 💸 One-click mutual fund orders
• 🔍 Browse available funds

🚀 Quick Start

Option 1: Automatic Installation (Recommended)

Install automatically via Smithery:

npx -y @smithery/cli install @aptro/zerodha-mcp --client claude

Option 2: Manual Installation

Follow the detailed setup steps below.

📋 Prerequisites

• Node.js and npm installed
• Python 3.8 or higher
• A Zerodha trading account
• Claude Desktop app

🔧 Setup Guide

Step 1: Create Zerodha Developer Account

1. Visit Kite Connect and sign up
2. Log in to your developer dashboard

Step 2: Register Your App

1. Navigate to Apps section in your dashboard
2. Click "Create a new app"
3. Fill in the application details:
   • App Name: Claude Zerodha Integration (or your preferred name)
   • App Category: Personal
   • Redirect URL: http://127.0.0.1:5000/zerodha/auth/redirect
   • Description: Brief description of your integration
4. Submit to create your app

Step 3: Obtain API Credentials

After app creation, you'll receive:

• API Key (Consumer Key)
• API Secret (Consumer Secret)

Keep these credentials secure—you'll need them in the next step.

Step 4: Configure Environment

1. Create a .env file in your project root directory
2. Add your credentials:

KITE_API_KEY=your_api_key_here
KITE_API_SECRET=your_api_secret_here

Important: Replace the placeholder values with your actual credentials.

Step 5: Install Dependencies

Install required Python packages:

uv pip install kiteconnect fastapi uvicorn python-dotenv httpx

Step 6: Configure Claude Desktop

Register the MCP server with Claude:

mcp install main.py

This makes all Zerodha trading functionality available through Claude.

💬 Usage Examples

Once configured, interact with your Zerodha account naturally through Claude:

Authentication

Can you check if I'm logged into Zerodha and authenticate if needed?

Portfolio & Account Management

What are my current margins?
Show me my holdings
What positions do I have open?

Market Data & Trading

What's the current price of RELIANCE and INFY?
Place a buy order for 10 shares of TCS at market price
Show me SBIN's price history for the last 30 days

Mutual Funds

Show my mutual fund holdings
List all my mutual fund orders
Buy ₹5000 worth of INF090I01239
Show all my active SIPs
Set up a monthly SIP of ₹2000 for INF090I01239 for 12 months
Cancel my SIP with ID 987654321

🔐 Authentication Flow

On first use:

1. Claude starts a local authentication server (port 5000)
2. Your browser opens to Zerodha's login page
3. After successful login, an access token is stored locally
4. Token remains valid for ~24 hours
5. Claude automatically re-authenticates when token expires

🛠️ Available MCP Tools

Authentication Tools

• check_and_authenticate - Verify auth status and login if needed
• initiate_login - Begin Zerodha login flow
• get_request_token - Retrieve authentication token

Stock Trading Tools

• get_holdings - View portfolio holdings
• get_positions - Check current positions
• get_margins - Check account margins
• place_order - Execute trades
• get_quote - Fetch real-time quotes
• get_historical_data - Retrieve price history

Mutual Fund Tools

• get_mf_orders - View mutual fund orders
• place_mf_order - Place MF orders
• cancel_mf_order - Cancel MF orders
• get_mf_instruments - Browse available funds
• get_mf_holdings - View MF portfolio
• get_mf_sips - List active SIPs
• place_mf_sip - Create new SIP
• modify_mf_sip - Modify existing SIP
• cancel_mf_sip - Cancel SIP

🐛 Troubleshooting

Authentication Issues

• Delete the .tokens file and re-authenticate
• Verify your .env credentials are correct
• Ensure the redirect URL in your Kite app matches: http://127.0.0.1:5000/zerodha/auth/redirect

Connection Problems

• Check that port 5000 is available
• Verify Zerodha API status at status.zerodha.com
• Ensure your internet connection is stable

API Errors

• Confirm your Zerodha developer account is active
• Check that your API subscription hasn't expired
• Review rate limits in Kite Connect documentation

🔒 Security & Privacy

Your data is safe:

• API credentials stored only in your local .env file
• Access tokens saved in local .tokens file
• Zero credential transmission to Claude or third parties
• Direct authentication with Zerodha's secure servers
• All trading operations happen through official Zerodha APIs

Best practices:

• Never commit .env or .tokens files to version control
• Keep your API credentials confidential
• Regularly review your API app permissions on Kite Connect
• Use strong passwords for your Zerodha account

📚 Additional Resources

• Kite Connect API Documentation
• Zerodha Developer Portal
• MCP Documentation

📄 License

[Add your license information here]

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

⚠️ Disclaimer

This is an unofficial integration. Use at your own risk. Always verify orders before execution. The developers are not responsible for any trading losses or issues arising from the use of this integration.