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