IBKR MCPサーバー

TWS APIを通じて、AIモデルにInteractive Brokers (IBKR) の取引データおよび機能への安全なアクセスを提供するModel Context Protocol (MCP) サーバーです。

⚠️⚠️⚠️ 免責事項 ⚠️⚠️⚠️

本ソフトウェアは教育および開発目的のものです。自己責任で使用してください。開発者は、本ソフトウェアの使用によって生じた金銭的損失について一切の責任を負いません。実際の資金を使用する前に、必ずペーパートレードでテストを行ってください。

Related MCP server: IBKR TWS MCP Server

🚀 機能

• 口座管理: ポジション、ポートフォリオ詳細、口座サマリーの取得

• 市場データ: 過去の価格データおよびリアルタイム市場情報の取得

• 取引操作: 注文の発注、ポジション管理、約定履歴の追跡

• MCP統合: MCPプロトコルをサポートするAIモデルとのシームレスな統合

• ワンショットCLI: コマンドごとの接続・実行・切断による迅速なスクリプト実行

• TWS自動起動 (macOS): TWSの起動とTOTP 2FAの自動入力を1コマンドで実行

• Claude Codeスキル: バンドルされた skills/ibkr-trading を介した自然言語による取引

• 安全機能: 読み取り専用モード、設定可能な取引制限、包括的なバリデーション

• 高可用性: 自動再接続、ハートビート監視、正常なエラー処理

📋 前提条件

• Python 3.10以上

• Interactive Brokers TWS または IB Gateway

• 有効なIBKR口座（テストにはペーパートレードを推奨）

🛠️ インストール

1. リポジトリのクローン:

   git clone https://github.com/happy-shine/ibkr_mcp.git
   cd ibkr_mcp

2. 依存関係のインストール:

   pip install -r requirements.txt

3. TWS/IB Gatewayの設定:

   • TWS/Gatewayの設定でAPI接続を有効にする

   • ソケットポートを設定する（デフォルト: ペーパートレードは7497、ライブは7496）

   • 必要に応じて信頼できるIPアドレスを設定する

4. サーバーの設定:

   cp config/config.yaml.example config/config.yaml
   # Edit config/config.yaml with your settings

🚀 使用方法

オプションA: MCPサーバー

python run.py

サーバーは以下の動作を行います:

1. TWS/IB Gatewayへの接続

2. 設定されたポートでMCPサーバーを起動

3. ハートビート監視の開始

4. すべてのアクティビティのログ記録

オプションB: ワンショットCLI

コマンドごとに接続して終了する軽量なCLIです。シェルスクリプトやアドホックなクエリに適しています。

python cli.py positions
python cli.py summary
python cli.py quote AAPL
python cli.py history AAPL --duration "1 M" --bar "1 day"
python cli.py buy AAPL 10 --type MKT --confirm
python cli.py orders

コマンド一覧を表示するには python cli.py --help を実行してください。

クォートデータに関する注意: リアルタイム市場データのサブスクリプションがない場合、quote は過去のデータから最新の日次バーを参照します（リアルタイムフィールドは含まれません）。

オプションC: TWS自動起動 (macOSのみ)

start_tws.py は IBC を介してTWSを起動し、二要素認証ダイアログを検出し、pyotp でTOTPコードを生成し、AppleScript (osascript) を通じて入力します。キーボードに触れることなく完全に自動化されたログインが可能です。

python start_tws.py          # launch and auto-fill 2FA
python start_tws.py --wait   # also block until API port 7496 is listening

要件 (macOS):

セットアップ:

1. IBCのmacOS向け手順に従ってインストールします（通常 ~/ibc/ に配置）。

2. ~/ibc/config.ini で以下を設定します:

   • TradingMode=live (または paper)

   • SecondFactorDevice=Mobile Authenticator

   • IBKRの認証情報

3. IBKRのTOTPシークレット（認証アプリのQRコードから得られるBase32文字列）を ~/.ibkr-totp-secret に保存するか、TOTP_SECRET としてエクスポートします。

4. システム設定 → プライバシーとセキュリティ → アクセシビリティ で、ターミナル（またはPythonランチャー）にアクセシビリティ権限を付与します。これはAppleScriptがTWSウィンドウを操作するために必要です。

プラットフォームに関する注意: start_tws.py はAppleScript/osascript に依存しており、macOS専用です。Linux/Windowsユーザーは、IBCを直接使用するか、GUI自動化レイヤー（Linuxなら xdotool、Windowsなら pywinauto など）を適応させてください。

利用可能なMCPツール

口座ツール

• get_positions() - 現在の口座ポジションを取得

• get_account_summary() - 口座残高と指標を取得

• get_portfolio() - 詳細なポートフォリオ情報を取得

市場データツール

• get_historical_data(symbol, duration, bar_size) - 過去の価格データを取得

• get_market_data(symbol) - リアルタイム市場データを取得

• get_quote_from_history(symbol) - クォートとして最新の日次バーを取得（サブスクリプション不要）

• get_contract_details(symbol) - 契約仕様を取得

• get_option_chain - オプションデータを取得

取引ツール

• place_order(symbol, action, quantity, order_type, ...) - 売買注文の発注

• get_orders(status) - 注文履歴とステータスの取得

• cancel_order(order_id) - 未約定注文のキャンセル

• get_trades() - 約定履歴の取得

AI対話の例

AI: "What are my current positions?"
→ Calls get_positions() tool

AI: "Buy 100 shares of AAPL at market price"
→ Calls place_order(symbol="AAPL", action="BUY", quantity=100, order_type="MKT")

AI: "Show me AAPL's price history for the last week"
→ Calls get_historical_data(symbol="AAPL", duration="1 W", bar_size="1 day")

🤖 Claude Codeスキル

skills/ibkr-trading/SKILL.md にコンパニオンとなるスキルがあります。これにより、Claude Code が自然言語のプロンプト（例: "show my positions", "quote AAPL"）から上記のCLIコマンドを実行できるようになります。

インストールするには、Claude Codeのスキルディレクトリにシンボリックリンクを作成してください:

ln -s "$(pwd)/skills/ibkr-trading" ~/.claude/skills/ibkr-trading

🔗 関連リンクとクレジット

• Interactive Brokers TWS API — 公式Python API (ibapi)

• IBC — Interactive Brokers Controller — TWS自動起動ツール (start_tws.py で使用)

• pyotp — TOTP/HOTPライブラリ (start_tws.py で使用)

• Model Context Protocol Specification

• FastMCP Framework

• Claude Code — バンドルされたスキルを利用するAIペアプログラミングCLI