IBKR MCP 서버

TWS API를 통해 AI 모델이 Interactive Brokers(IBKR) 거래 데이터 및 기능에 안전하게 액세스할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

⚠️⚠️⚠️ 면책 조항 ⚠️⚠️⚠️

이 소프트웨어는 교육 및 개발 목적으로 제공됩니다. 사용에 따른 책임은 전적으로 사용자에게 있습니다. 본 소프트웨어 사용으로 인해 발생하는 어떠한 재정적 손실에 대해서도 작성자는 책임을 지지 않습니다. 실제 자금을 사용하기 전에 반드시 모의 거래(paper trading)로 테스트하십시오.

Related MCP server: IBKR TWS MCP Server

🚀 주요 기능

• 계정 관리: 포지션, 포트폴리오 세부 정보 및 계정 요약 정보 조회

• 시장 데이터: 과거 가격 데이터 및 실시간 시장 정보 검색

• 거래 작업: 주문 실행, 포지션 관리 및 체결 내역 추적

• MCP 통합: MCP 프로토콜을 지원하는 AI 모델과 원활하게 통합

• One-shot CLI: 빠른 스크립팅을 위한 명령별 연결-실행-연결 해제 방식

• 자동 TWS 실행 (macOS): TWS를 시작하고 TOTP 2FA를 자동 입력하는 단일 명령

• 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: One-shot 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는 과거 데이터를 통해 가장 최근의 일일 바(daily bar)를 가져옵니다(실시간 필드 없음).

옵션 C: 자동 TWS 실행 (macOS 전용)

start_tws.py는 IBC를 통해 TWS를 실행하고, 2단계 인증(2FA) 대화 상자를 감지하여 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. macOS 지침에 따라 IBC를 설치합니다(일반적으로 ~/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가 자연어 프롬프트(예: "내 포지션 보여줘", "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