Zerodha MCP Server & Client

Zerodha MCP 服务与客户端

一个基于 Python 的交易助手，可连接到 Zerodha MCP 服务，帮助用户管理其交易账户。

功能

• 账户管理：管理 Zerodha 交易账户、订单和持仓
• 交互式聊天界面：通过自然语言界面执行交易操作
• MCP 集成：基于 Model Context Protocol 实现标准化通信
• Zerodha API 集成：使用 Zerodha 的 API 与交易平台交互
• Agno Agent：使用 Agno Agent 与交易平台交互
• Google ADK Agent：使用 Google ADK Agent 与交易平台交互

技术栈

• 协议：Model Context Protocol (MCP)
• Agent 框架：
  • Agno
  • Google ADK

工具

• 下单：在交易平台下单
• 修改订单：修改交易平台中的订单
• 取消订单：取消交易平台中的订单
• 获取订单：获取交易平台中的订单
• 获取订单历史：获取交易平台中的订单历史
• 获取订单成交记录：获取交易平台中的订单成交记录
• 获取保证金：获取交易平台中的保证金信息
• 获取持仓：获取交易平台中的持仓
• 获取仓位：获取交易平台中的仓位
• 获取用户资料：获取交易平台中的用户资料

前置条件

• Python
• Zerodha 交易账户，并通过此处获取个人 API 访问权限
• Zerodha API 密钥和密钥
• OpenAI API 密钥（用于 Agno Agent）
• Gemini API 密钥或 Application Default Credentials（用于 Google ADK Agent）

安装

1. 克隆代码仓库：

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

2. 创建并激活虚拟环境：

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

3. 安装依赖项：

pip install -r requirements.txt

4. 设置环境变量：

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

# Edit the .env file with your credentials

5. 创建 .env 文件并填写配置：

# 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

服务端用法

该服务提供一组用于与 Zerodha 交易平台交互的工具。启动服务：

1. 确保已在 .env 文件中正确配置 Zerodha API 凭据。

2. 使用以下任一方法启动服务：

# 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

该服务提供以下工具：

• get_login_url：获取用于用户身份验证的登录 URL
• get_access_token：使用请求令牌生成访问令牌
• get_user_profile：获取用户的 Zerodha 资料信息
• get_margins：获取可用保证金和资金详情
• get_holdings：获取投资组合持仓
• get_positions：获取当前仓位
• get_orders：获取当天的所有订单
• get_order_history：获取指定订单的历史记录
• get_order_trades：获取订单产生的成交记录
• place_order：下新订单
• modify_order：修改现有订单
• cancel_order：取消订单

客户端用法

该项目提供三种客户端实现：

1. 使用 Agno 框架（client/agno_client.py）
2. 使用带 Gradio Web 界面的 Agno（client/agno_gradio_client.py）
3. 使用 Google ADK（client/google_adk_client.py）

所有客户端都会连接到 MCP 服务，并提供用于交易操作的交互界面。

运行 Agno 客户端

1. 确保 .env 文件中包含 OPENAI_API_KEY。
2. 使用以下任一方法启动客户端：

# 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

运行 Google ADK 客户端

1. 确保已通过 Google AI 完成身份验证：可以设置 GOOGLE_API_KEY 环境变量（并取消 .env 文件中对应行的注释），也可以使用 Application Default Credentials（运行 gcloud auth application-default login）。
2. 使用以下任一方法启动客户端：

# 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

运行 Gradio Web 界面

1. 确保 .env 文件中包含 OPENAI_API_KEY。
2. 启动 Gradio Web 界面：

# 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. 打开 Web 浏览器，访问终端中显示的 URL（通常为 http://localhost:7860）。

4. 使用 Web 界面：

   • 输入主机和端口，连接 MCP 服务
   • 使用自然语言与 AI 助手聊天
   • 通过用户友好的界面管理你的 Zerodha 账户

Gradio 界面提供：

• 通过主机/端口配置轻松管理连接
• 与 AI 助手实时聊天的界面
• 连接状态的可视化反馈
• 适合移动设备的响应式设计

客户端配置

两个客户端都支持通过多个来源进行配置，优先级如下：

1. 命令行参数（最高优先级）
2. 环境变量
3. .env 文件变量

配置选项：

• 环境变量：MCP_HOST 和 MCP_PORT
• 命令行参数：--host 和 --port
• .env 文件变量：MCP_HOST、MCP_PORT、OPENAI_API_KEY 和 GOOGLE_API_KEY

默认值（未提供配置时）：

• 主机：localhost
• 端口：8001

客户端会自动从项目根目录中的 .env 文件加载环境变量。请确保 .env 文件包含必要的配置：

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

3. 客户端将使用提供的配置自动连接到 MCP 服务。

4. 连接后，你可以使用自然语言命令与助手互动。例如：

   • “显示我的投资组合持仓”
   • “我目前有哪些持仓？”
   • “买入 10 股 RELIANCE，提交市价单”
   • “取消订单 ID 123456”

5. 要退出客户端，请在出现提示时输入 'quit'。

开发

项目结构

• client/agno_client.py：使用 Agno 实现的 MCP 客户端
• client/google_adk_client.py：使用 Google ADK 实现的 MCP 客户端
• client/agno_gradio_client.py：使用 Gradio 和 Agno 实现的 Web 界面
• server.py：集成 Zerodha API 的 MCP 服务实现
• generate_token.py：用于生成访问令牌的工具
• requirements.txt：项目依赖项
• .env：环境配置

贡献

1. Fork 此代码库
2. 创建功能分支
3. 提交更改
4. 推送到该分支
5. 创建 Pull Request

许可证

本项目根据 Apache License 2.0 许可——详情请参阅 LICENSE 文件。

致谢

• 使用 Agno 构建
• 使用 Google ADK 构建
• 使用 MCP 进行标准化通信
• 由 KiteConnect 提供支持，用于集成 Zerodha API