Zerodha MCP

🚀 Zerodha-MCP

这是一个用于Zerodha mcp服务器的仓库，提供了一个生产就绪的、符合MCP协议的交易服务器，可用于集成Zerodha Kite Connect API。该服务器在Google Colab中开发，可部署到任何地方，并且带有完整的模拟经纪商，方便在没有API密钥的情况下进行开发。

🚀 快速开始

选项1：Google Colab（推荐用于开发）

1. 打开Colab笔记本：
   • 点击在Colab中打开，并粘贴colab_notebook.md中的笔记本内容。
2. 运行设置单元格：

   !pip install fastmcp pydantic sqlalchemy structlog
   # 按顺序运行所有单元格
   

3. 测试系统：

   # 笔记本中包含的快速测试
   await test_system()
   

4. 下载并推送到GitHub：

   !zip -r trading-server.zip src/ tests/ docs/
   # 下载ZIP文件并推送到你的GitHub仓库
   

选项2：本地开发

# 克隆仓库
git clone https://github.com/YOUR_USERNAME/zerodha-trading-mcp.git
cd zerodha-trading-mcp

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # 在Windows上使用：venv\Scripts\activate

# 安装依赖项
pip install -r requirements.txt

# 配置环境
cp .env.example .env
# 使用你的设置编辑.env文件

# 运行测试
pytest tests/ -v

# 启动MCP服务器
python src/server.py

✨ 主要特性

• 🤖 MCP协议：可与Claude和其他MCP客户端无缝协作。
• 📊 完整的订单管理：从信号到执行的全生命周期跟踪。
• 🛡️ 风险管理：可配置的限制、断路器和头寸控制。
• 💼 投资组合跟踪：实时损益计算和头寸管理。
• 🎭 模拟经纪商：无需API访问即可进行逼真的开发模拟。
• 🔌 Kite Connect就绪：带有详细集成指南的即插即用适配器。
• 📝 结构化日志记录：用于订单、风险事件和系统操作的JSON日志。
• ✅ 全面测试：单元测试和集成测试覆盖率超过80%。

📦 安装指南

依赖安装

在Google Colab或本地环境中，按照上述快速开始部分的步骤安装所需的依赖项。

环境配置

编辑.env文件进行配置：

# 环境
ENVIRONMENT=development
DEBUG=true
DRY_RUN=false           # 设置为true以在不进行真实订单的情况下进行测试

# 经纪商
BROKER_TYPE=mock        # 准备好后更改为 'kite'

# 风险限制
MAX_POSITION_SIZE=500000.0       # 每个头寸50万卢比
MAX_TOTAL_EXPOSURE=2000000.0     # 总风险敞口200万卢比
MAX_POSITIONS=10                 # 最大并发头寸数
MAX_DAILY_LOSS_PCT=5.0          # 5%的断路器

# Kite Connect（准备好后填写）
KITE_API_KEY=your_key_here
KITE_API_SECRET=your_secret_here
KITE_ACCESS_TOKEN=

💻 使用示例

基础用法

以下是使用Claude进行交易的示例：

用户：以市价买入10股SBIN股票

Claude：我将为你下单。
[调用place_order工具，符号=SBIN，操作=买入，数量=10]

服务器响应：
✅ 订单提交成功
- 符号：SBIN
- 操作：买入
- 数量：10
- 状态：已提交
订单ID：abc-123-def

高级用法

可用的MCP工具

1. place_order - 提交交易订单（买入/卖出）
2. get_positions - 查看所有未平仓头寸及损益情况
3. get_portfolio - 获取完整的投资组合摘要
4. cancel_order - 取消待处理订单
5. get_order_status - 检查特定订单的状态
6. get_order_history - 查看过去的订单
7. get_risk_metrics - 获取当前的风险敞口和限制

📚 详细文档

项目结构

zerodha-trading-mcp/
├── src/
│   ├── server.py              # MCP服务器入口点
│   ├── config.py              # 配置管理
│   ├── mcp/                   # MCP协议处理程序
│   ├── core/                  # 交易引擎
│   │   ├── risk_manager.py
│   │   ├── order_manager.py
│   │   └── portfolio_tracker.py
│   ├── adapters/              # 经纪商适配器
│   │   ├── base.py
│   │   ├── mock_broker.py
│   │   └── kite_adapter.py    # Kite Connect占位符
│   ├── models/                # 数据模型
│   │   ├── signal.py
│   │   ├── order.py
│   │   ├── position.py
│   │   └── portfolio.py
│   └── utils/                 # 实用工具
│       └── logger.py
├── tests/                     # 测试套件
│   ├── unit/
│   └── integration/
├── docs/                      # 文档
│   ├── API.md
│   ├── SETUP.md
│   └── KITE_INTEGRATION.md
├── logs/                      # 日志文件（已添加到gitignore）
├── data/                      # 数据库（已添加到gitignore）
├── .env.example               # 环境模板
├── requirements.txt
└── README.md

Kite Connect集成

前提条件

1. 拥有Zerodha交易账户。
2. 订阅Kite Connect API（每月2000卢比）。
3. 在Kite Connect控制台中创建应用。

集成步骤

# 1. 获取API凭证
KITE_API_KEY=your_key
KITE_API_SECRET=your_secret

# 2. 更新.env文件
BROKER_TYPE=kite

# 3. 安装kiteconnect
pip install kiteconnect

# 4. 取消注释Kite适配器代码
# 详细说明请参阅src/adapters/kite_adapter.py

# 5. 进行身份验证
# 运行身份验证流程以获取访问令牌

# 6. 以干运行模式启动
DRY_RUN=true

# 7. 使用小订单进行测试
# 先下1股的订单

# 8. 上线
DRY_RUN=false

完整指南请参阅docs/KITE_INTEGRATION.md。

🔧 技术细节

风险管理

内置的风险控制措施：

日志记录

在logs/目录中生成结构化的JSON日志：

• orders_{date}.jsonl - 所有订单活动。
• risk_{date}.jsonl - 风险检查结果。
• system_{date}.jsonl - 系统事件。
• errors_{date}.jsonl - 错误跟踪。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

⚠️ 重要提示

⚠️ 重要提示

本软件仅用于教育目的。交易具有风险。请始终：

• 从小头寸开始。
• 使用适当的风险管理措施。
• 在实盘交易前进行充分测试。
• 切勿投入超过你承受能力的资金。

💡 使用建议

按照开发工作流程逐步进行，先在模拟环境中完善策略，再进行API集成和实盘交易。

📧 支持

• 📖 文档
• 🐛 报告问题
• 💬 讨论

🙏 致谢

• 为Model Context Protocol构建。
• 为Zerodha Kite Connect设计。
• 使用Claude进行开发。

准备好开始AI交易了吗？克隆、配置并开始吧！🚀