Zerodha MCP Server & Client

Zerodha MCP サーバー＆クライアント

Zerodha MCP サーバーに接続し、ユーザーによる取引口座の管理を支援する Python ベースの取引アシスタントです。

機能

• 口座管理：Zerodha の取引口座、注文、ポジションを管理します
• 対話型チャットインターフェース：取引操作に対応する自然言語インターフェースです
• MCP 統合：標準化された通信を実現する Model Context Protocol を基盤としています
• Zerodha API 統合：Zerodha の API を使用して取引プラットフォームと連携します
• Agno エージェント：Agno Agent を使用して取引プラットフォームと連携します
• Google ADK エージェント：Google ADK Agent を使用して取引プラットフォームと連携します

技術スタック

• プロトコル：Model Context Protocol (MCP)
• エージェントフレームワーク：
  • Agno
  • Google ADK

ツール

• 注文の発注：取引プラットフォームで注文を発注します
• 注文の変更：取引プラットフォームで注文を変更します
• 注文のキャンセル：取引プラットフォームで注文をキャンセルします
• 注文の取得：取引プラットフォームの注文を取得します
• 注文履歴の取得：取引プラットフォームの注文履歴を取得します
• 注文約定の取得：取引プラットフォームの注文約定を取得します
• 証拠金の取得：取引プラットフォームの証拠金を取得します
• 保有資産の取得：取引プラットフォームの保有資産を取得します
• ポジションの取得：取引プラットフォームのポジションを取得します
• ユーザープロフィールの取得：取引プラットフォームのユーザープロフィールを取得します

前提条件

• Python
• こちらから取得した Personal API アクセス権を持つ Zerodha 取引口座
• Zerodha API キーとシークレット
• OpenAI API キー（Agno エージェント用）
• Gemini API キーまたは Application Default Credentials（Google ADK エージェント用）

インストール

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：注文をキャンセルします

クライアントの使用方法

このプロジェクトでは、3 種類のクライアント実装を提供しています：

1. Agno フレームワークを使用するクライアント（client/agno_client.py）
2. Gradio ウェブインターフェース付きの 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_API_KEY 環境変数を設定する（および .env 内でコメントを解除する）か、Application Default Credentials を使用して（gcloud auth application-default login を実行して）、Google AI への認証を済ませてください。
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. 接続したら、自然言語のコマンドを使ってアシスタントとやり取りできます。例：

   • 「ポートフォリオの保有銘柄を表示して」
   • 「現在のポジションを教えて」
   • 「RELIANCE を 10 株、成行注文で購入して」
   • 「注文 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. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更をコミットします
4. ブランチにプッシュします
5. プルリクエストを作成します

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については LICENSE ファイルを参照してください。

謝辞

• Agno を使用して構築されています
• Google ADK を使用して構築されています
• 標準化された通信に MCP を使用しています
• Zerodha API 統合に KiteConnect を使用しています