What is Zerodha Mcp

Zerodha MCP is a Python-based trading assistant that connects to the Zerodha MCP server, enabling users to manage their trading accounts efficiently.

Use cases

Use cases include placing, modifying, and canceling orders, retrieving order history, checking margins and holdings, and managing user profiles on the trading platform.

How to use

To use Zerodha MCP, clone the repository, set up a virtual environment, and install the necessary dependencies. Users need a Zerodha trading account with API access and can interact with the trading platform through a natural language interface.

Key features

Key features include account management, an interactive chat interface, MCP integration for standardized communication, and integration with Zerodha’s API, Agno Agent, and Google ADK Agent.

Where to use

Zerodha MCP can be used in financial trading environments, particularly for users who trade on the Zerodha platform and require automated trading assistance.

Zerodha MCP Server & Client

A Python-based trading assistant that connects to a Zerodha MCP server to help users manage their trading account.

Features

• Account Management: Manage Zerodha trading account, orders, and positions
• Interactive Chat Interface: Natural language interface for trading operations
• MCP Integration: Built on the Model Context Protocol for standardized communication
• Zerodha API Integration: Uses Zerodha’s API to interact with the trading platform
• Agno Agent: Uses Agno Agent to interact with the trading platform
• Google ADK Agent: Uses Google ADK Agent to interact with the trading platform

Tech Stack

• Protocol: Model Context Protocol (MCP)
• Agent Framework:
  • Agno
  • Google ADK

Tools

• Place Orders: Place orders in the trading platform
• Modify Orders: Modify orders in the trading platform
• Cancel Orders: Cancel orders in the trading platform
• Get Orders: Get orders in the trading platform
• Get Order History: Get order history in the trading platform
• Get Order Trades: Get order trades in the trading platform
• Get Margins: Get margins in the trading platform
• Get Holdings: Get holdings in the trading platform
• Get Positions: Get positions in the trading platform
• Get User Profile: Get user profile in the trading platform

Prerequisites

• Python
• Zerodha trading account with Personal API access from here
• Zerodha API key and secret
• OpenAI API key (for Agno Agent)
• Gemini API key or Application Default Credentials (for Google ADK Agent)

Installation

1. Clone the repository:

git clone https://github.com/mtwn105/zerodha-mcp-server-client.git
cd zerodha-mcp-server-client

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up environment variables:

# Copy the example environment file
cp .env.example .env

# Edit the .env file with your credentials

5. Create a .env file with your configuration:

# Server Configuration
ZERODHA_API_KEY=your_api_key
ZERODHA_API_SECRET=your_api_secret
PORT=8001
SERVER_MODE=sse  # or stdio

# Client Configuration
MCP_HOST=localhost
MCP_PORT=8001
OPENAI_API_KEY=your_openai_api_key
# GOOGLE_API_KEY=your_google_api_key

Server Usage

The server provides a set of tools for interacting with the Zerodha trading platform. To start the server:

1. Make sure your .env file is properly configured with your Zerodha API credentials.

2. Start the server using one of the following methods:

# Using environment variables
python server.py

# Or using command line arguments
python server.py --api-key your_api_key --api-secret your_api_secret --port 8001 --mode sse

The server provides the following tools:

• get_login_url: Get the login URL for user authentication
• get_access_token: Generate access token using request token
• get_user_profile: Get user’s Zerodha profile information
• get_margins: Get available margins and fund details
• get_holdings: Get portfolio holdings
• get_positions: Get current positions
• get_orders: Get all orders for the day
• get_order_history: Get history of a specific order
• get_order_trades: Get trades generated by an order
• place_order: Place a new order
• modify_order: Modify an existing order
• cancel_order: Cancel an order

Client Usage

This project provides three client implementations:

1. Using the Agno framework (client/agno_client.py)
2. Using Agno with Gradio web interface (client/agno_gradio_client.py)
3. Using Google ADK (client/google_adk_client.py)

All clients connect to the MCP server and provide an interactive interface for trading operations.

Running the Agno Client

1. Ensure your .env file includes OPENAI_API_KEY.
2. Start the client using one of the following methods:

# Using environment variables from .env file
python client/agno_client.py

# Using command line arguments
python client/agno_client.py --host localhost --port 8001

# Using a combination (command line arguments take precedence)
MCP_HOST=localhost MCP_PORT=8001 python client/agno_client.py --host otherhost --port 9000

Running the Google ADK Client

1. Ensure you have authenticated with Google AI, either by setting the GOOGLE_API_KEY environment variable (and uncommenting it in .env) or by using Application Default Credentials (run gcloud auth application-default login).
2. Start the client using one of the following methods:

# Using environment variables from .env file
python client/google_adk_client.py

# Using command line arguments
python client/google_adk_client.py --host localhost --port 8001

# Using a combination (command line arguments take precedence)
MCP_HOST=localhost MCP_PORT=8001 python client/google_adk_client.py --host otherhost --port 9000

Running the Gradio Web Interface

1. Ensure your .env file includes OPENAI_API_KEY.
2. Start the Gradio web interface:

# Using environment variables from .env file
python client/agno_gradio_client.py

# Using command line arguments for server configuration
python client/agno_gradio_client.py --host localhost --port 8001

3. Open your web browser and navigate to the URL shown in the terminal (typically http://localhost:7860).

4. Use the web interface to:

   • Connect to the MCP server by entering the host and port
   • Chat with the AI assistant using natural language
   • Manage your Zerodha account through a user-friendly interface

The Gradio interface provides:

• Easy connection management with host/port configuration
• Real-time chat interface with the AI assistant
• Visual feedback for connection status
• Mobile-friendly responsive design

Client Configuration

Both clients support configuration through multiple sources, with the following precedence:

1. Command-line arguments (highest precedence)
2. Environment variables
3. .env file variables

Configuration options:

• Environment variables: MCP_HOST and MCP_PORT
• Command-line arguments: --host and --port
• .env file variables: MCP_HOST, MCP_PORT, OPENAI_API_KEY, and GOOGLE_API_KEY

Default values (if no configuration is provided):

• Host: localhost
• Port: 8001

The client automatically loads environment variables from the .env file in the project root directory. Make sure your .env file contains the necessary configuration:

# Client Configuration
MCP_HOST=localhost
MCP_PORT=8001
OPENAI_API_KEY=your_openai_api_key
# GOOGLE_API_KEY=your_google_api_key

3. The client will automatically connect to the MCP server using the provided configuration.

4. Once connected, you can interact with the assistant using natural language commands. For example:

   • “Show me my portfolio holdings”
   • “What are my current positions?”
   • “Place a market order for 10 shares of RELIANCE”
   • “Cancel order ID 123456”

5. To exit the client, type ‘quit’ when prompted.

Development

Project Structure

• client/agno_client.py: MCP client implementation using Agno
• client/google_adk_client.py: MCP client implementation using Google ADK
• client/agno_gradio_client.py: Web interface using Gradio and Agno
• server.py: MCP server implementation with Zerodha API integration
• generate_token.py: Utility for generating access tokens
• requirements.txt: Project dependencies
• .env: Environment configuration

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

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

Acknowledgments

• Built using Agno
• Built using Google ADK
• Uses MCP for standardized communication
• Powered by KiteConnect for Zerodha API integration