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交易了嗎？克隆、配置並開始吧！🚀