Ib MCP

🚀 Interactive Brokers API MCP プロジェクト

このプロジェクトは、Interactive BrokersのWeb APIを基に構築された、Model Context Protocol (MCP) を用いたAPIインターフェースを提供します。TWS APIと比べ、Web APIはよりモダンで柔軟な基盤を提供し、本プロジェクトの目標に適しています。

⚠️ 重要提示

このプロジェクトは現在積極的に開発中です。機能が不完全な場合や、破壊的な変更が発生する可能性があります。

🚀 クイックスタート

このセクションでは、プロジェクトのセットアップと使用方法について説明します。

Docker Desktopのセットアップ

YOUTUBE でクイックウォークスルーを確認できます。

1. リポジトリをクローンし、環境変数を設定してイメージをビルドします。

   # リポジトリをクローンする
   git clone https://github.com/rcontesti/IB_MCP.git
   
   # プロジェクトディレクトリに移動する
   cd IB_MCP
   
   # .env.exampleファイルを.envにコピーし、必要に応じて編集する
   cp .env.example .env
   
   # イメージをビルドする
   docker compose up --build -d
   

2. IBアカウントと資格情報で認証します。 イメージが起動した後、https://{GATEWAY_BASE_URL}:{GATEWAY_PORT}（例: https://localhost:5055/）にアクセスしてログインします。ログインパスはAPIゲートウェイコンテナのログにも記載されています。 成功すると、「Client login succeeds」と表示されるURLにリダイレクトされます。

3. MCPサーバーの設定ファイルをVS Codeのsettings.jsonに追加します。

以下の環境パラメータがあるとします。

MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=5002
MCP_SERVER_PATH=/mcp
MCP_TRANSPORT_PROTOCOL=streamable-http

VS Codeのsettings.jsonにおけるMCPサーバーのスニペットは次のようになります。

{
  ...
        },
        "chat.mcp.discovery.enabled": true,
        "mcp": {
            "inputs": [],
            "servers": {
                "time": {
                "command": "docker",
                "args": ["run", "-i", "--rm", "mcp/time"]
                },
                "ib-web": {
                    "type": "http",
                    "url": "http://localhost:5002/mcp/",
                }
            }
        },
        "workbench.colorTheme": "Tomorrow Night Blue"
}

または、プロジェクトのルートに.vscode/mcp.jsonファイルを作成し、以下の内容を記述することもできます。

{
    "servers": {
        "ib-mcp-server": {
            "type": "http",
            "url": "http://localhost:5002/mcp/"
        }
    },
    "inputs": []
}

詳細は Use MCP servers in VS Code (Preview) を参照してください。

4. CopilotでMCPを起動します。

マルチコンテナセットアップの制限事項

• ユーザーは、Client Portal Gatewayと同じマシンのブラウザを通じてログインして認証する必要があります。
• すべてのAPIエンドポイント呼び出しは、Client Portal Gatewayが認証された同じマシンで行う必要があります。
• /gw/api、/oauth、または/oauth2で始まるエンドポイントは、Client Portal Gatewayでの使用はサポートされていません。

セッション管理

追加の/iserver/auth/ssodh/initエンドポイントは、バックエンドとの証券セッションを再開するために使用され、これを通じて保護された/iserverエンドポイントにアクセスできます。

新しいリクエストを送信せず、または/tickleエンドポイントを少なくとも5分ごとに維持しない場合、セッションは約6分後にタイムアウトします。

セッションのタイムアウトを防ぐために、/tickleエンドポイントを定期的に呼び出すことをお勧めします。約1分ごとにこのエンドポイントを呼び出すことが推奨されます。

証券セッションがタイムアウトしたが、セッションが依然としてIBKRバックエンドに接続されている場合、/auth/statusへのレスポンスはconnected:true および authenticated:false を返します。/iserver/auth/ssodh/initエンドポイントを呼び出すと、新しい証券セッションが初期化されます。

✨ 主な機能

• このプロジェクトは、Interactive BrokersのWeb APIを基に構築された、Model Context Protocol (MCP) を用いたAPIインターフェースを提供します。
• 自動的なエンドポイント生成機能を目指していますが、現在は手動でエンドポイントを構築しています。
• OAuthの追加も予定されています。

📦 インストール

上記の「クイックスタート」セクションの「Docker Desktopのセットアップ」を参照してください。

💻 使用例

基本的な使用法

# リポジトリをクローンする
git clone https://github.com/rcontesti/IB_MCP.git

# プロジェクトディレクトリに移動する
cd IB_MCP

# .env.exampleファイルを.envにコピーし、必要に応じて編集する
cp .env.example .env

# イメージをビルドする
docker compose up --build -d

高度な使用法

{
    "servers": {
        "ib-mcp-server": {
            "type": "http",
            "url": "http://localhost:5002/mcp/"
        }
    },
    "inputs": []
}

📚 ドキュメント

TWS APIとWeb APIの比較

• TWS API (Trader Workstation API): レガシーで強力なAPIです。非常に強力で高速で機能が豊富ですが、より複雑で、TWSデスクトップソフトウェアまたはIB Gatewayをマシン上で継続的に実行する必要があります。
• Web API (Client Portal API): モダンで開発者に優しいRESTful APIです。使用がはるかに簡単で、標準のHTTPSを使用し、スタンドアロンです（デスクトップソフトウェアは必要ありません）。ただし、TWS APIよりもパフォーマンスが低く、機能が少ないです。

比較表

TWS APIの詳細な利点と欠点

✅ TWS APIの利点

1. 比類のない機能性: これは最大の利点です。TWSデスクトッププラットフォームでできることのほとんどを行うことができます。複雑なマルチレッグコンボ注文（オプション戦略）の作成、数十種類のアルゴリズム注文タイプ（VWAP、TWAP）のアクセス、金融アドバイザーのための配分管理などが可能です。
2. 高いパフォーマンスと低レイテンシ: 直接のソケット接続を使用することで、TWS APIは非常に高速です。速度を重視して構築されており、レイテンシに敏感な戦略には唯一の選択肢です。マーケットデータのストリーミングはリアルタイムで効率的です。
3. 広範な履歴データ: 履歴データへの深いアクセスを提供し、APIを通じて直接広範なバックテストと分析を行うことができます。
4. 成熟度と堅牢性: このAPIは数十年にわたって存在しています。十分にテストされ、安定しており、多くのプログラミング言語で豊富な例とサードパーティのラッパーがある大きなコミュニティがあります。

❌ TWS APIの欠点

1. TWS/Gatewayの依存関係: これは最大の欠点です。アプリケーションはスタンドアロンではありません。トレーダーワークステーションまたはより軽量なIB Gatewayのインスタンスをサーバーまたはコンピューター上で24時間365日実行し、ログインする必要があります。これは運用上の複雑さ、障害の原因、およびリソースのオーバーヘッドを追加します。
2. 急な学習曲線: このAPIは直感的ではありません。メッセージIDと特定の呼び出しシーケンスを持つ独自のリクエスト/レスポンスモデルを使用します。エラーハンドリングはトリッキーで、デバッグには標準のウェブプロトコルではなく、独自のアーキテクチャを理解する必要があります。
3. 複雑さ: プロトコルはバイナリであり、クライアントライブラリ（IBの公式ライブラリやサードパーティのラッパーなど）を使用して対話する必要があります。単純なJSONペイロードを送信するだけではありません。

Web API (Client Portal API) の詳細な利点と欠点

✅ Web APIの利点

1. 使いやすさとモダンな標準: これは標準的なRESTful APIです。ウェブAPIを使用したことがあれば、すぐに使い慣れるでしょう。HTTPSリクエストを行い、クリーンで人間が読みやすいJSONを取得します。これにより、参入障壁が大幅に低下します。
2. デスクトップの依存性がない: これは最大の特長です。アプリケーションはどこでも実行できます（クラウドサーバー、サーバーレス関数など）。別のTWS/Gatewayプロセスを維持する必要はありません。これにより、デプロイとメンテナンスが大幅に簡素化されます。
3. ウェブとモバイルに最適: 標準的なウェブAPIであるため、ウェブベースのダッシュボード、モバイルアプリケーションの構築、または他のウェブサービスへのIBKRデータの統合に最適です。
4. 安全な認証: OAuthを使用しており、安全で委任されたアクセスの業界標準です。ユーザーがアプリにアカウントへのアクセス許可を与えるアプリケーションに最適です。

❌ Web APIの欠点

1. 機能性が制限されている: TWSで利用可能なすべての機能を公開していません。標準的な注文（成行、指値、逆指値）を出すことはできますが、TWS APIがサポートする複雑なアルゴリズムまたはマルチレッグコンボ注文は見つかりません。
2. パフォーマンスが低い: HTTPS/JSONのオーバーヘッドにより、TWS APIの直接のソケット接続よりも本質的に遅くなります。高頻度またはレイテンシに敏感な取引戦略には適していません。
3. レート制限: ウェブベースのサービスとして、すべてのクライアントが公平に利用できるように、リクエストに対するより明示的なレート制限が適用されます。
4. 新しく成熟度が低い: 現在はかなり安定していますが、TWS APIよりも新しいです。時々、機能が欠けていることや、数十年にわたるTWS APIのドキュメントほど洗練されていないことがあります。

どちらを選ぶべきか？

TWS APIを選ぶ場合:

• 本格的な自動アルゴリズム取引システムを構築している場合。
• 戦略がレイテンシに敏感な場合。
• 複雑な注文タイプ（オプションスプレッド、コンボ、またはIBKRの組み込みアルゴリズム）を出す必要がある場合。
• カスタムで機能豊富なデスクトップ取引アプリケーションを構築している場合。
• IB Gatewayを24時間365日実行する運用オーバーヘッドに慣れている場合。

Web API (Client Portal API) を選ぶ場合:

• ウェブダッシュボードまたはモバイルアプリを構築してポートフォリオを監視する場合。
• 単純な取引ボットを構築して基本的な注文を実行する場合（例: 「AAPLが150ドルに達したら100株を買う」）。
• レポートまたは分析ツールを構築している場合。
• 開発速度と使いやすさが、生のパフォーマンスやすべての機能へのアクセスよりも重要である場合。
• 専用のTWS/Gatewayインスタンスを実行できない、または実行したくない場合。

🔧 技術詳細

アーキテクチャ

このプロジェクトは4つの主要なコンポーネントで構成されています。

• api_gateway: DockerコンテナでInteractive Brokers Client Portal Gatewayを実行し、IB REST APIへの安全なアクセスを可能にします。
• ticker_service: 「セッション再開」セクションで詳述されているように、定期的に/tickleエンドポイントを呼び出してInteractive Brokersセッションを維持し、セッションのタイムアウトを防ぎます。このサービスはDockerコンテナで実行されます。
• routers_generator: 公式ドキュメントに基づいて自動的にFastAPIルーターを作成し、routersディレクトリに保存します。
• mcp_server: FastMCPで構築されたMCPサーバーで、APIゲートウェイと対話します。このサービスもDockerコンテナで実行されます。

📦 Interactive Brokers Client Portal Gateway Dockerコンテナ

このDockerコンテナは、Interactive Brokers (IB) Client Portal Gateway をセットアップして実行します。これは、アプリケーションがIB REST APIを介して接続するために必要です。

🔧 このコンテナの機能

• ベースイメージ: IB Gatewayとの互換性のためにeclipse-temurin:21（Java 21）を使用します。
• 依存関係のインストール: ゲートウェイアーカイブを抽出するためにunzipをインストールします。
• ゲートウェイのダウンロード: 公式のInteractive Brokersソースから最新バージョンのClient Portal Gatewayを取得し、解凍します。
• 設定:
  • カスタムのconf.yamlを予想されるパス (gateway/root/conf.yaml) にコピーして、ゲートウェイを設定します。
  • カスタムのrun_gateway.shスクリプトをコンテナのエントリポイントとして追加します。
• ポートの公開: ゲートウェイが使用するデフォルトポートであるポート5055を公開します。必要に応じて.envでオーバーライドしてください。
• 起動コマンド: 設定ファイルを使用してゲートウェイを実行します。

このセットアップは、コンテナ化された環境でInteractive Brokers REST APIゲートウェイを安全に実行するための自己完結型で再現可能な環境を提供します。

📦 Interactive Brokers Routers Generator Dockerコンテナ [WIP]

公式のOpen Api Jsonファイルが検証に失敗するため、現在はルーターを手動で開発しています。詳細は Future Work と Endpoints Status を参照してください。

📦 IB MCP Server Dockerコンテナ

このDockerコンテナは、Interactive Brokers (IB) Model Context Protocol (MCP) Server をセットアップして実行します。これは、IB APIゲートウェイと対話するためのインターフェースを提供します。

🔧 このコンテナの機能

• ベースイメージ: uvを備えた軽量なPython 3.11環境のghcr.io/astral-sh/uv:python3.11-bookworm-slimを使用します。
• 依存関係のインストール: システム依存関係のcurlをインストールし、uv syncを使用してpyproject.tomlからPython依存関係をインストールします。
• 設定: pyproject.tomlとmcp_serverディレクトリ全体をコンテナにコピーします。PYTHONPATHを/appに、UV_CACHE_DIRを/tmp/uv-cacheに設定します。
• ポートの公開: MCP_SERVER_PORT環境変数で指定されたポート（例: 5002）を公開します。
• 起動コマンド: uv run -- python /app/mcp_server/fastapi_server.pyを使用してFastAPIサーバーを実行します。

このセットアップは、MCPサーバーがIB Client Portal Gatewayと通信できるようにするコンテナ化された環境を提供します。

🔗 参考資料

• IB WEB API Reference

• IB WEB API openapi docs 古い情報です！

• IB WEB API Reference page

• FAST MCP

• FAST MCP Documentation

• FAST MCP openapi integration

• ibeam

• fastapi-codegen

• openapi spec validator repo

• openapi spec validator docs

🤝 コントリビューション

このプロジェクトへのコントリビューションを歓迎します！コントリビュートしたい場合は、以下のガイドラインに従ってください。

1. リポジトリをフォークし、mainからブランチを作成します。
2. バグ報告は、明確な説明と再現手順を記載したIssueを作成してください。
3. 機能提案は、アイデアを議論するためのIssueを作成してください。
4. プルリクエストを送信して、バグ修正、新機能、または改善を提案してください。コードが既存のスタイルに準拠し、関連するテストを含み、明確なコミットメッセージがあることを確認してください。

📄 ライセンス

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