mcp-ibkr

Claude Code と Interactive Brokers (IBKR) を接続するための独自 MCP (Model Context Protocol) サーバー。ペーパートレーディング口座に対する読み取り専用モードから始めます。

プロジェクトの状態: 12フェーズ中12フェーズ完了。現在の状態のセクションを参照してください。

1. このプロジェクトとは

Claude Code と IBKR の間のブリッジです。Claude Code がこのサーバーを起動し、サーバーは「ツール」(名前と説明を持つ関数) を公開し、ユーザーが口座情報・ポジション・市場情報を求めると Claude がそれらを使用します。どのツールも IBKR と直接通信せず、すべて統合レイヤーを経由します。

Related MCP server: IB Portfolio Tracker MCP Server

2. アーキテクチャ

Claude Code (cliente MCP)
      │  stdio / JSON-RPC
      v
Servidor MCP (src/server.py)
      │
      v
Tool Registry (src/tools/*)
      │
      v
Capa de integración IBKR (src/ibkr/*)
      │  ib_async → socket TCP
      v
IB Gateway (Paper Trading, puerto 4002)
      │
      v
Interactive Brokers

3. フォルダ構成

mcp-ibkr/
├── src/
│   ├── server.py          # Punto de entrada del servidor MCP
│   ├── ibkr/
│   │   └── connection.py     # UNICO lugar que habla con ib_async / IB Gateway
│   ├── tools/
│   │   ├── registry.py       # Registro central: conecta archivos de herramienta con el servidor
│   │   ├── account/            # Saldo, resumen de cuenta, verificar conexión
│   │   ├── market/              # Precio, cotización, históricos
│   │   ├── positions/            # Posiciones abiertas, P&L
│   │   └── orders/                # Consultar (activa) + crear/cancelar (ACTION, deshabilitadas)
│   ├── config/
│   │   └── settings.py       # Carga .env, rechaza arrancar en config insegura
│   └── utils/
│       └── risk.py            # RiskLevel: READ_ONLY / ACTION
├── tests/
├── .env.example
├── .gitignore
├── .mcp.json          # Registro del servidor para Claude Code (scope project)
├── pyproject.toml      # Configuracion de pytest
├── requirements.txt     # Dependencias exactas (pip freeze)
└── README.md

4. 要件

• Python 3.11+ (3.14 で動作確認済み)。

• Git。

• curl (セクション5で get-pip.py を、セクション6で IB Gateway インストーラーをダウンロードするため)。

• IB Gateway がインストール済みで、ペーパートレーディングセッションにログインしていること (セクション6参照)。

5. インストールと設定

cd ~/mcp-ibkr

# Crear entorno virtual aislado para este proyecto
python3 -m venv --without-pip .venv

# Instalar pip dentro del venv (no viene incluido con --without-pip)
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
.venv/bin/python3 /tmp/get-pip.py

# Instalar dependencias del proyecto
.venv/bin/python3 -m pip install -r requirements.txt

# Configuración local (nunca se sube a Git)
cp .env.example .env

requirements.txt に関する注意: 直接インストールするパッケージは4つだけ (mcp、ib_async、python-dotenv、pytest) ですが、pip freeze にはそれらのパッケージの依存関係 (依存関係の依存関係) も含まれるため、ファイルにはそれ以上の行があります。これは正常な動作です — プロジェクトがそれらすべてのライブラリを直接使用しているという意味ではありません。

注意: Debian/Ubuntu システムでは、python3 -m venv 単体では、システムパッケージ python3-venv が不足していると失敗する場合があります (sudo apt install python3-venv でインストールできます)。sudo へのアクセスがない場合、--without-pip と venv 内への手動 pip インストール (上記の手順) の組み合わせで、管理者権限を必要とせずに同等に隔離された環境が得られます。

6. IBKR との接続 (ペーパートレーディング)

1. IB Gateway をインストールします (公式ダウンロード、stable-standalone):

   curl -o ibgateway-stable-standalone-linux-x64.sh \
     https://download.interactivebrokers.com/installers/ibgateway/stable-standalone/ibgateway-stable-standalone-linux-x64.sh
   chmod u+x ibgateway-stable-standalone-linux-x64.sh
   ./ibgateway-stable-standalone-linux-x64.sh

2. 起動して、明示的に "Paper Trading" ("Live Trading" ではなく) を選択して、ペーパートレーディングのユーザー名/パスワードでログインします。

3. API ポートが 4002 (ペーパー) であることを確認します。次のように確認できます:

   ss -ltnp | grep 4002   # deberia aparecer un proceso "java" escuchando

4. .env.example を .env にコピーし (まだの場合)、設定が異なる場合は値を調整します。

これが安全な理由: src/config/settings.py は、IBKR_PORT が正確に 4002 でない場合、また IBKR_PAPER_TRADING_CONFIRMED が true でない場合、起動を拒否します。さらに、接続 (src/ibkr/connection.py) は readonly=True で開かれるため、注文ツールが存在する前から、IB Gateway は API レベルでの注文送信の試みをすべて拒否します。

7. Claude Code の設定

サーバーは .mcp.json (プロジェクトルート) に scope project で登録されています。つまり、このファイルは Git でバージョン管理され、このリポジトリを Claude Code で開く人は誰でも提案されたサーバーを確認できます — ただし、自動的には実行されません: このフォルダ内でセッションを開いて承認するまで、Claude Code は「Pending approval」としてマークします。

cd ~/mcp-ibkr
claude    # al iniciar, Claude Code te preguntará si confías en mcp-ibkr

いつでもサーバーの状態を確認するには:

claude mcp list
claude mcp get mcp-ibkr

削除したい場合:

claude mcp remove mcp-ibkr -s project

8. 利用可能なツール

9. ツールの追加 / 変更 / 削除 / 無効化の方法

各ツールは src/tools/<カテゴリ>/ 内の1つのファイルで、次の形式です (実際の例として src/tools/account/verificar_conexion_ibkr.py を参照):

from mcp.types import ToolAnnotations
from src.utils.risk import RiskLevel

NAME = "mi_herramienta"
DESCRIPTION = "Que hace, cuando usarla, que devuelve, si modifica la cuenta."
ANNOTATIONS = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
ENABLED = True
RISK_LEVEL = RiskLevel.READ_ONLY  # o RiskLevel.ACTION si modifica algo

def mi_herramienta(parametro: str) -> str:
    return "resultado"

関数名は NAME と同じにする必要があります — これにより、中央レジストリ (src/tools/registry.py) が自動的に見つけられます。RISK_LEVEL が ACTION の場合、ENABLED = True に加えて .env に IBKR_ENABLE_ACTION_TOOLS=true が必要です (セクション11参照) — 意図的に独立した2つのキーです。

ANNOTATIONS について: destructiveHint と idempotentHint は、readOnlyHint=False の場合にのみ意味を持ちます (MCP の仕様にそう記載されています) — そのため、読み取り専用ツールでは readOnlyHint と openWorldHint で十分です。RISK_LEVEL が ACTION の場合のみ追加してください (src/tools/orders/crear_orden.py のように)。

ツールの追加

1. 対応するカテゴリにファイルを作成します (新しいカテゴリを作成する場合は、下記参照)。

2. そのカテゴリの __init__.py の TOOLS リストにファイル名 (.py なし) を追加します。

3. Claude Code のセッションを再起動して認識させます (Claude Code はサーバー起動時にツールを1回だけ読み取ります。claude mcp list は接続状態を確認するだけで、再読み込みはしません)。

ツールの変更

ファイルを直接編集します — DESCRIPTION、関数パラメータ、内部ロジックなど。registry.py を触る必要はありません。

ツールの削除

ファイルを削除し、そのカテゴリの __init__.py の TOOLS から名前を削除します。

ツールの無効化 (削除せずに)

ファイル内で ENABLED = False に設定します。registry.py が自動的にスキップします。

新しいカテゴリの作成

TOOLS: list[str] = [...] を定義する __init__.py を持つフォルダ src/tools/<カテゴリ>/ を作成し、src/tools/registry.py の CATEGORIES にカテゴリ名を追加します。

10. テスト

cd ~/mcp-ibkr
.venv/bin/python3 -m pytest tests/ -v

• tests/test_server.py — サーバーが起動し、期待されるツールを公開すること (Claude Code が接続時に見るものと同じ)、読み取り専用ツールが適用外のアノテーションを設定しないこと、各ツールが IBKR が利用できない場合に例外を漏らさず、代わりに親しみやすいメッセージで応答すること。

• tests/test_settings.py — 設定が 4002 以外のポートと IBKR_PAPER_TRADING_CONFIRMED の欠如を拒否すること。

• tests/test_connection.py — 接続レイヤーが接続試行を直列化すること (シミュレートされた IBKR を使用。実際の Gateway は不要): 2つのツールがほぼ同時に呼び出されても、並行して実行される接続試行が2つになることはない。

• tests/test_risk_system.py — ACTION ツール (crear_orden、cancelar_orden) がデフォルトで登録されないこと、注文の検証 (数量、タイプ、価格) が無効なパラメータを拒否すること。

• tests/test_ibkr_integration.py — IB Gateway に対する実際の接続。Gateway が実行されていない場合、このテストはスキップされます (失敗しません) — これは想定内で、プロジェクトのエラーではありません。

注文に関連するすべてのテストは、validar_parametros_orden を単独で使用するか (IBKR に触れずに)、crear_orden がデフォルトで無効であることに依存しています: このプロジェクトのテストは、ペーパートレーディングでも実際の注文を送信しません。

11. ペーパートレーディングからライブトレーディングへ

⚠️ ライブトレーディングはこのプロジェクトではまだサポートされておらず、crear_orden/cancelar_orden はデフォルトで無効です。 以下はセキュリティレイヤーの説明であり、考えずに有効化するための勧誘ではありません。

実際の注文が誤って送信されるのを防ぐ独立した3つのレイヤーがあります:

1. 必須ポート 4002 — src/config/settings.py は、IBKR_PORT がペーパートレーディングのポートと正確に一致しない場合、起動を拒否します。このバージョンのプロジェクトには、ポート 4001 (ライブ) を使用するコードパスは一切ありません。

2. ACTION ツールの二重キー — crear_orden と cancelar_orden は、自身のファイルで ENABLED = True かつ .env で IBKR_ENABLE_ACTION_TOOLS=true が必要です。どちらもデフォルトでは有効になっていません。両方ともサーバー起動時にのみ読み取られます: サーバー実行中に変更した場合、変更を反映するには Claude Code セッションの再起動が必要です。

3. API レベルの読み取り専用接続 — IBKR_ENABLE_ACTION_TOOLS が false の間、src/ibkr/connection.py は readonly=True で接続します: 誰かが上記2つのレイヤーを回避できたとしても、IB Gateway は注文を拒否します。

将来、ペーパートレーディングで注文送信を有効にすると決めた場合の手順は: src/tools/orders/crear_orden.py の検証を確認・強化し、.env に IBKR_ENABLE_ACTION_TOOLS=true を設定し、注文ファイルで ENABLED = True に設定します。実際のライブトレーディングのサポートは、このプロジェクトでは実装されておらず、計画もされていません — 検討する前に、完全に別のセキュリティレビューが必要です。

12. 現在の状態

• フェーズ 1 — アーキテクチャとコンセプト

• フェーズ 2 — プロジェクトの最小構造

• フェーズ 3 — 開発環境

• フェーズ 4 — 最小 MCP サーバー

• フェーズ 5 — Claude Code と MCP の接続

• フェーズ 6 — 最初のテストツール

• フェーズ 7 — IB Gateway との接続 (ペーパートレーディング)

• フェーズ 8 — 照会ツール

• フェーズ 9 — 検証・リスクシステム

• フェーズ 10 — 注文ツール (ブロック済み)

• フェーズ 11 — 完全なテスト

• フェーズ 12 — 最終ドキュメント