Zerodha MCP

🚀 Zerodha-MCP

ZerodhaのMCPサーバー用のリポジトリです。Zerodha Kite Connect APIと統合した、本番環境で使用可能なMCP対応の取引サーバーです。

🚀 クイックスタート

オプション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%以上のカバレッジがあります。

📁 プロジェクト構造

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/                      # ログファイル (gitignored)
├── data/                      # データベース (gitignored)
├── .env.example               # 環境テンプレート
├── requirements.txt
└── README.md

💻 使用例

基本的な使用法

# 例: Claudeで取引する
User: Buy 10 shares of SBIN at market price

Claude: I'll place that order for you.
[Calls place_order tool with symbol=SBIN, action=BUY, quantity=10]

Server Response:
✅ Order Submitted Successfully
- Symbol: SBIN
- Action: BUY
- Quantity: 10
- Status: SUBMITTED
Order ID: abc-123-def

高度な使用法

# 利用可能なMCPツール
1. **place_order** - 取引注文を送信する (BUY/SELL)
2. **get_positions** - すべての建玉と損益を表示する
3. **get_portfolio** - 完全なポートフォリオの概要を表示する
4. **cancel_order** - 保留中の注文をキャンセルする
5. **get_order_status** - 特定の注文のステータスを確認する
6. **get_order_history** - 過去の注文を表示する
7. **get_risk_metrics** - 現在のリスクエクスポージャーと制限を表示する

⚙️ 設定

.env ファイルを編集して設定します。

# 環境
ENVIRONMENT=development
DEBUG=true
DRY_RUN=false           # 実際の注文なしでテストする場合はtrueに設定する

# ブローカー
BROKER_TYPE=mock        # 準備ができたら 'kite' に変更する

# リスク制限
MAX_POSITION_SIZE=500000.0       # 1ポジションあたり ₹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=

🧪 テスト

# すべてのテストを実行する
pytest tests/ -v

# カバレッジを含めて実行する
pytest tests/ --cov=src --cov-report=html

# 特定のテストファイルを実行する
pytest tests/unit/test_trading.py -v

# 統合テストのみを実行する
pytest tests/integration/ -v

📊 モックブローカーの機能

モックブローカーは、リアルな取引動作をシミュレートします。

• ✅ ランダムな注文遅延 (50-200ms)
• ✅ スリッページシミュレーション (0.05-0.15%)
• ✅ 部分約定シナリオ
• ✅ 注文拒否ケース (5%の割合)
• ✅ 市場価格の変動
• ✅ 買気配値と売気配値のスプレッド

APIアクセスなしでの開発とテストに最適です！

🔌 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 を参照してください。

📈 リスク管理

組み込みのリスクコントロールがあります。

すべての制限は .env を通じて設定可能です。

📝 ロギング

logs/ ディレクトリに構造化JSONログがあります。

• orders_{date}.jsonl - すべての注文活動
• risk_{date}.jsonl - リスクチェック結果
• system_{date}.jsonl - システムイベント
• errors_{date}.jsonl - エラー追跡

🛠️ 開発ワークフロー

フェーズ1: モック取引 (現在)

• ✅ Google Colabで開発する
• ✅ モックブローカーでテストする
• ✅ あなたの戦略を完成させる
• ✅ GitHubに保存する

フェーズ2: API統合

• 🔶 Kite Connectの資格情報を取得する
• 🔶 認証を実装する
• 🔶 紙取引でテストする
• 🔶 小さな実際の注文を行う

フェーズ3: 本番環境

• ⏳ 徐々にスケールアップする
• ⏳ パフォーマンスを監視する
• ⏳ 機能を追加する
• ⏳ 戦略を最適化する

🚦 ステータス

• ✅ 完了: モック取引、リスク管理、ポートフォリオ追跡
• 🔶 未実施: Kite Connectの統合 (APIキーが必要)
• ⏳ 将来的な予定: ダッシュボード、高度な分析、AIシグナルの統合

🤝 コントリビューション

コントリビューションを歓迎します！ 以下の手順を実行してください。

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 新しい機能のテストを書く
4. すべてのテストが通過することを確認する
5. プルリクエストを送信する

📄 ライセンス

MITライセンス - 詳細は LICENSE ファイルを参照してください。

⚠️ 免責事項

このソフトウェアは教育目的で提供されています。取引にはリスクが伴います。常に以下のことを行ってください。

• 小さなポジションから始める
• 適切なリスク管理を行う
• 本番取引の前に十分にテストする
• 失うことができる以上の金額を取引しない

📧 サポート

• 📖 ドキュメント
• 🐛 問題を報告する
• 💬 ディスカッション

🙏 謝辞

• Model Context Protocol のために構築されました。
• Zerodha Kite Connect 用に設計されました。
• Claude を使用して開発されました。

AIでの取引を始める準備はできましたか？ クローンして、設定して、始めましょう！ 🚀