IBKR Portfolio Builder

ibkr-portfolio-builder-mcp

Interactive Brokersを使ったトップダウン型ポートフォリオ構築のためのリモートMCPサーバーです。Claude.aiのカスタムコネクター、Claude Code MCP、または任意のHTTP MCPクライアントでの利用を想定して構築されています。

多くのibkr-mcpサーバーが公開するのは、get_quote、get_position、place_orderといった個別の照会プリミティブです。このサーバーが公開するのは、リサーチのワークフローです。戦略の意図（value / growth / income / momentum / quality / events / …）をタグ付けした16カテゴリ、468件のスクリーナーからなる型付きカタログ、スキャンごとの適用可能な金融商品、逆ペアのリンク、リアルタイムのニュースや口座情報へのアクセスを提供します。これにより、LLMはボトムアップで銘柄を探すのではなく、実際にトップダウンでポートフォリオを構築できます（セクターや戦略を選ぶ → スキャンを実行する → ニュースと照合する → 候補を絞り込む）。

このサーバーを作った理由

既存のコミュニティ製IBKR-MCPサーバーは、IBKRを「単一銘柄を1つずつ調べる」データソースとして扱っているため、このサーバーを作りました。これは多くの個人投資家向け証券会社のUIと同じ考え方ですが、適切なポートフォリオ構築の実際の進め方とは異なります。

優れたトップダウン型のワークフローは、次のようになります。

1. マクロの投資仮説（「金利がまもなく下がり、配当銘柄の評価が見直されるはず」）→
2. 戦略の意図（「米国大型株を対象に、クオリティ重視のインカム系スクリーニングを表示して」）→
3. スクリーナーの組み合わせ（配当利回り＋ROE＋低負債のスクリーニングを実行し、結果を照合する）→
4. イベント／ニュースの状況（「この中に今後2週間で決算発表がある銘柄はあるか。ネガティブなアナリストの評価変更はあるか」）→
5. 候補を絞り込む（「条件に基づいて順位付けした5銘柄を、詳細なデューデリジェンスに進められる状態で提示する」）。

LLMでこれを実現するには、MCPサーバーは生のAPIだけでなく、リサーチ用の語彙を公開する必要があります。このサーバーは、そのギャップを埋めます。

• 型付きスキャンカタログ — 16カテゴリ（Fundamentals、Price Movement、Dividends、Options & Volatility、Events & Earnings、52/26/13 Week High-Low、ESG、Bonds、…）にわたる468件のIBKRスキャンコードに、28種類の戦略意図タグ（value、growth、quality、income、momentum_up、momentum_down、analyst、technical、gap、volatility、events、leverage、efficiency、risk_adjusted、…）を自動で付与しています。LLMは「米国株向けのvalueスキャンにはどんなものがあるか」と尋ねると、学習データからスキャンコードを推測する代わりに、明確でフィルタリング可能な回答を得られます。
• 逆ペアのリンク — すべてのHIGH_X ↔ LOW_XおよびX_ASC ↔ X_DESCのペアを事前に計算しているため、LLMは推測せずに極性を反転できます（「LOW_PE_RATIOの反対は何か？」）。
• スキャンごとの金融商品マップ — カタログには、各スキャンがSTK、ETF、OPT、BONDなどのどの金融商品に適用されるかが記録されています。これにより、LLMが債券商品にRefinitivのスキャンを送って空の結果を受け取ることがなくなります。
• フィルターカタログ — 数値フィルター（priceAbove、peRatioBelow、divYieldAbove、growthRateAbove、avgVolumeAbove、marketCapAbove、…）をカテゴリ別に分類した、別の型付きマップです。金融商品ごとの適用に関する注記も含まれています。
• ニュースとスクリーナーを1つのツールで提供 — 同じコネクター、同じ認証情報、同じ会話を利用できます。LLMはコンテキストを切り替えずに、スキャン結果を最近の見出しや今後の決算発表と照合できます。
• 2種類の認証方式 — Claude.aiのカスタムコネクター向けの完全なOAuth 2.1（DCR＋PKCE＋well-knowns）に加え、それ以外のすべての用途向けの静的Bearerトークンにも対応しています。サーバーもツールも同じものを使います。

まだ初期段階のサーバーです。IBKR APIには、ペーパー口座で実際に取得できる情報に多くの制約があります（特に過去のニュースを参照する権限）。ただし、カタログとワークフローの構成は本番利用に対応できる状態であり、LLM主導のリサーチループを支える重要な要素です。

クイック情報

• トランスポート： /mcp での Streamable HTTP。
• 認証： OAuth 2.1（PKCE + RFC 7591 Dynamic Client Registration）および／または静的ベアラートークン。AUTH_MODE で選択できます。
• 永続化： 現時点ではインメモリのみです（セッション／DCR クライアント／OAuth トークンはコンテナの再起動時にリセットされます）。Redis はロードマップに記載されています。詳しくは以下をご覧ください。
• IBKR 接続： この compose では、ib-gateway（ghcr.io/gnzsnz/ib-gateway:stable）を兄弟サービスとして実行します。デフォルトでは、ペーパー口座を読み取り専用 API モードで使用します。
• 構築基盤： FastMCP + ib_async。

ツール

IBKR 公式 MCP の読み取り専用ツール 9 個と同等の機能を備えています（書き込み／注文指示ツール 2 個は対象外です。ロードマップをご覧ください）。さらに、このサーバーの存在理由であるスクリーナー／ニュース／カタログツール 5 個を提供します。

ツール	機能
ib_account_summary	接続中のペーパー口座またはライブ口座の NetLiquidation／BuyingPower／TotalCashValue／AvailableFunds／UnrealizedPnL。
ib_positions	管理対象の口座における保有中のポジション。数量／平均取得原価／時価評価／未実現損益を含みます。
ib_open_orders	現在有効な注文と、ステータス、約定済み／残数量、平均約定価格。
ib_trades	最近の約定（days_back の期間。IBKR の履歴は約 7 日に制限されています）。
ib_price_snapshot	米国株の現在の買値／売値／最終価格／高値／安値／出来高。IBKR のマーケットデータ制限に関するメッセージを明確に表示します。
ib_price_history	任意の期間／バーサイズ（1 day、1 hour、5 mins、…）の OHLCV バー。マーケットデータのサブスクリプションにかかわらず、常に利用できます。
ib_search_contracts	名前／ティッカーの一部から、IBKR のコントラクトデータベースをあいまい検索します。
ib_contract_details	コントラクトの完全なメタデータ。long_name、industry、category、subcategory、取引時間、有効な取引所が含まれます。セクターを考慮したトップダウン・スクリーニングの要です。
ib_scan_catalog	型付きのスキャンカタログです。category、strategy、instrument、フリーテキストの query で絞り込めます。list_meta=true を指定すると、利用可能なカテゴリと戦略の全リストも返します。
ib_filter_catalog	カテゴリ（price、volume、market_cap、fundamentals、technical、options）ごとにまとめられたフィルターパラメーターコードと、対象銘柄種別に関する注記。
ib_screener_codes	生の scan-parameters.xml コードを部分一致で検索します（レガシー／フォールバック）。厳選カタログにまだ含まれていない、新しいベンダーコードの検索に便利です。
ib_screener	IBKR のスキャンを実行します。scan_code、instrument、location、任意の価格／出来高フィルターを指定します。順位 + ティッカー + 取引所を返します。
ib_news_providers	サブスクリプション中の IBKR ニュースプロバイダー（Briefing.com、Dow Jones など）を一覧表示します。
ib_news_for_symbol	サブスクリプション中のすべてのプロバイダーから、米国株の見出しを取得します。見出しのみを返します。アカウントに過去のニュースを閲覧する権限がない場合は、明確な notice フィールドを表示します。
ib_news_article	provider_code + article_id を指定して、個別の記事本文を取得します。⚠️ 記事ごとの料金が発生する場合があります（特に Dow Jones）。

注文発注に関する注記。 IBKR 公式 MCP には Create Order Instruction と Delete Order Instruction もあります。このサーバーでは、意図的にこれらを提供していません。ib-gateway は READ_ONLY_API=yes モードで動作するため、ツール呼び出し先を誤っても注文は発注されません。注文執行は、独自の承認ゲートを備えた別のサービスで行うものです。IBKR に接続することなくローカルストアに書き込む「ステージングのみ」の指示ツールを検討する可能性については、ロードマップをご覧ください。

認証

AUTH_MODE は、サーバーが受け入れる認証方式を選択します。デフォルトは both です。

モード	受け入れる認証方式	必須の環境変数
oauth	OAuth 発行トークンのみ。Claude.ai のカスタムコネクターに必要です。	LOGIN_PASSWORD
bearer	静的な Authorization: Bearer <token> のみ。OAuth の認証フローを省略します。CLI クライアント、Claude Code、独自のスクリプトに最適です。	STATIC_BEARER_TOKEN
both (デフォルト)	OAuth トークンまたは静的ベアラートークンのいずれか。	LOGIN_PASSWORD または STATIC_BEARER_TOKEN の少なくとも一方。

OAuth エンドポイント（/authorize、/token、/register、/.well-known/*、/login）は常に登録されます。bearer モードでは機能しないため、README からこれらのエンドポイントを参照する必要はありません。

シークレットの生成

uv run --no-project python -c "import secrets; print(secrets.token_urlsafe(48))"   # bearer token
uv run --no-project python -c "import secrets; print(secrets.token_urlsafe(48))"   # session secret

静的ベアラートークンの使用

curl -X POST https://YOUR.DOMAIN/mcp \
  -H "Authorization: Bearer $STATIC_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Claude.ai から接続する（OAuth）

設定 → コネクター → カスタムコネクターを追加 → URL：https://YOUR.DOMAIN/mcp → OAuth クライアント ID／シークレットは空欄のままにします（Claude.ai は DCR を使用します）。Claude.ai が OAuth フローを開始すると、LOGIN_PASSWORD の入力を求められます。

実行

cp .env.example .env
# edit .env: set TWS_USERID / TWS_PASSWORD (paper account), LOGIN_PASSWORD, STATIC_BEARER_TOKEN, PUBLIC_BASE_URL
docker compose up -d

デフォルトでは、GitHub Container Registry から公開済みのマルチアーキテクチャイメージを取得します：ghcr.io/adwiteeymauriya/ibkr-portfolio-builder-mcp:latest。代わりにローカルでビルドする場合（例：ソースを編集しながら試す場合）は、まず docker compose build ibkr-mcp を実行します。

初回起動後、ib-gateway が IBKR へのログインを完了するまで約 60～90 秒かかります。docker logs -f ibkr-mcp-gateway でログを追跡できます。

ローカルでのみ使用する場合（ベアラートークンを使うクライアント、Claude.ai は使用しない場合）は、これで十分です。http://localhost:8000/mcp でサービスが開始されます。Claude.ai のカスタムコネクターには、パブリックインターネット上の HTTPS URL が必要なため、前段に TLS 対応のリバースプロキシを配置する必要があります。

Claude.ai 用に TLS を設定する

どちらかを選んでください。どちらも、利用可能な https://your-host/mcp と有効な証明書を用意できます。

オプション 1 — Cloudflare Tunnel（パブリック IP 不要、ポートフォワーディング不要）。 サーバーがホームネットワーク上、または NAT 配下の VM で動作している場合に最適です。Cloudflare はホスト名と TLS を無料で提供し、トンネルデーモンはサーバーから Cloudflare のエッジへ接続します。

# One-time: install cloudflared, then
cloudflared tunnel login
cloudflared tunnel create ibkr-mcp
cloudflared tunnel route dns ibkr-mcp ibkr-mcp.your-domain.com

~/.cloudflared/config.yml：

tunnel: ibkr-mcp
credentials-file: /home/you/.cloudflared/<TUNNEL_ID>.json
ingress:
  - hostname: ibkr-mcp.your-domain.com
    service: http://localhost:8000
  - service: http_status:404

cloudflared tunnel run ibkr-mcp で実行します（または cloudflared service install で systemd ユニットとしてインストールします）。次に、.env で PUBLIC_BASE_URL=https://ibkr-mcp.your-domain.com を設定し、docker compose restart ibkr-mcp を実行します。

オプション 2 — Let's Encrypt を使った Caddy リバースプロキシ。 サーバーにパブリック IP があり、ポート 80／443 が開いている場合に最適です。Caddy は証明書を自動的に取得します。

Caddyfile：

ibkr-mcp.your-domain.com {
    reverse_proxy localhost:8000
}

caddy run で実行します（またはシステムサービスとしてインストールします：sudo caddy start と systemd ユニットを使用）。.env の変更は上記と同じです。

どちらの場合も、PUBLIC_BASE_URL は Claude.ai に指定する URL と完全に一致している必要があります。Claude.ai は OAuth 発行者がこれと一致するかを検証します。

LLM プロンプトの例（トップダウンのワークフロー）

1. Discovery:
   "List the strategies and categories available in ib_scan_catalog."

2. Strategy intent:
   "Find me value scans for US stocks. Show me their inverse codes too."

3. Composition:
   "Run LOW_PE_RATIO on STK.US.MAJOR with priceAbove $20 and avgVolumeAbove
    1,000,000, top 30. Cross-reference with HIGH_RETURN_ON_EQUITY top 30.
    Show me overlap."

4. Event context:
   "For the overlap list, check ib_news_for_symbol for any negative
    headlines in the last 7 days, and Events & Earnings scans for
    upcoming earnings within 14 days."

5. Narrow:
   "Rank the survivors by liquidity and tell me which two you'd dig
    into next."

ロードマップ

分野	項目
認証	Redis を使ったセッション、DCR クライアント、OAuth トークン
認証	トークンごとのスコープ（read-only、read-news、screener-only、...）
金融商品	オプション（チェーン、グリークス、IV／価格計算）
金融商品	先物（ContFuture、Bag によるコンボ）
金融商品	債券（検索＋気配値）
金融商品	外国為替＋暗号資産
取引所	米国外株式のルーティング（EU、HK、JP、AU）
取引所	通貨に対応した ib_account_summary
リサーチ	Reuters のファンダメンタルズ（reqFundamentalDataAsync）
リサーチ	リアルタイムのストリーミングバー＋ティックごとのデータ
リサーチ	レベル 2 の注文板
リサーチ	日次 PnL ストリーム（pnlAsync、pnlSingleAsync）
リサーチ	アドバイザーのサブアカウント（reqFamilyCodesAsync）
リサーチ	マルチホップクエリ向けのカタログ → Memgraph
リサーチ	ib_news_search の対象拡大
リスク	ib_what_if_order（証拠金の事前確認、注文は実行しません）
リスク	ローカルのステージング指示ツール（IBKR への書き込みなし）

これらに関する Issue や PR を歓迎します。

ディレクトリ構成

.
├── Dockerfile
├── docker-compose.yml             # connector + ib-gateway, internal IBKR network
├── pyproject.toml                 # uv-managed: fastmcp, itsdangerous, uvicorn, ib_async
├── uv.lock
├── .env.example
├── LICENSE                        # MIT
├── scan-parameters.xml            # IBKR's authoritative scan params (raw XML)
├── scanner_reference.json         # IBKR-categorized scanner reference
├── scanner_params.json            # Flat dump of scan codes + filters
├── scripts/
│   └── build_catalog.py           # Regenerates src/connector/data/* from the three source files above
└── src/
    └── connector/
        ├── settings.py            # env-driven config (incl. AUTH_MODE)
        ├── auth.py                # LoginGatedOAuthProvider + static bearer override + /login
        ├── ibkr.py                # ib_async connection helper (connect-per-call)
        ├── screener.py            # raw scan-parameters.xml substring search (fallback tool)
        ├── catalog.py             # typed scan + filter catalog loaders + filtering
        ├── tools.py               # 15 MCP tools wired into FastMCP
        ├── server.py              # FastMCP + Starlette wiring + uvicorn entry
        └── data/
            ├── scan_catalog.json  # generated
            └── filter_catalog.json # generated

ライセンス

MIT。

謝辞

• ヘッドレスの ib-gateway イメージを提供する gnzsnz/ib-gateway-docker に感謝します。
• 非同期 IBKR クライアントを提供する ib_async に感謝します。
• OAuth を標準でサポートする MCP サーバーフレームワークを提供する FastMCP に感謝します。

免責事項

このソフトウェアは、お使いの Interactive Brokers アカウントと通信します。デフォルトでは、読み取り専用 API モードのペーパーアカウントで動作するため、ツールが試みても注文は発注できません。ライブアカウントに切り替える場合は、自己責任で行ってください。ツールの出力は投資助言を構成するものではありません。戦略タグ付けは用語を補助するものであり、推奨を行う仕組みではありません。