IBKR MCP Server
IBKR MCP 서버
TWS API를 통해 AI 모델이 Interactive Brokers(IBKR) 거래 데이터 및 기능에 안전하게 액세스할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.
⚠️⚠️⚠️ 면책 조항 ⚠️⚠️⚠️
이 소프트웨어는 교육 및 개발 목적으로 제공됩니다. 사용에 따른 책임은 전적으로 사용자에게 있습니다. 본 소프트웨어 사용으로 인해 발생하는 어떠한 재정적 손실에 대해서도 작성자는 책임을 지지 않습니다. 실제 자금을 사용하기 전에 반드시 모의 거래(paper trading)로 테스트하십시오.
Related MCP server: Interactive Brokers 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 계정 (테스트를 위한 모의 거래 권장)
🛠️ 설치
저장소 복제:
git clone https://github.com/happy-shine/ibkr_mcp.git cd ibkr_mcp의존성 설치:
pip install -r requirements.txtTWS/IB Gateway 구성:
TWS/Gateway 설정에서 API 연결 활성화
소켓 포트 설정 (기본값: 모의 거래용 7497, 실거래용 7496)
필요한 경우 신뢰할 수 있는 IP 주소 구성
서버 구성:
cp config/config.yaml.example config/config.yaml # Edit config/config.yaml with your settings
🚀 사용법
옵션 A: MCP 서버
python run.py서버는 다음을 수행합니다:
TWS/IB Gateway에 연결
구성된 포트에서 MCP 서버 시작
하트비트 모니터링 시작
모든 활동 기록
옵션 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):
구성 요소 | 목적 | 링크 |
TWS 실행 및 로그인 입력 자동화 | ||
RFC 6238 TOTP 코드 생성 | ||
| macOS 기본 제공; 2FA 대화 상자 제어 | 내장 |
설정:
macOS 지침에 따라 IBC를 설치합니다(일반적으로
~/ibc/).~/ibc/config.ini에서 다음을 설정합니다:TradingMode=live(또는paper)SecondFactorDevice=Mobile AuthenticatorIBKR 자격 증명
IBKR TOTP 비밀키(인증기 QR 코드의 Base32 문자열)를
~/.ibkr-totp-secret에 저장하거나TOTP_SECRET으로 내보냅니다.시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용에서 터미널(또는 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에서 사용)Claude Code — 번들 스킬을 사용하는 AI 페어 프로그래밍 CLI
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Connect brokerage accounts to AI assistants: holdings, orders, asset lookup, and approved trading.
Unified financial infrastructure connecting AI agents directly to trade live/demo brokerage accounts, Web3 non-custodial wallets, real-time market data across equities, ETFs, crypto, forex, options, DeFi swaps, and prediction markets, institutional research feeds, and algorithmic strategy backtesters.
Agentic brokerage access to a US brokerage account: quotes, orders, positions, cash and documents.
Connect AI agents to bank accounts, transactions, balances, and investments.
Related MCP Servers
- AlicenseBqualityCmaintenanceEnables AI assistants to interact with Interactive Brokers trading accounts to retrieve market data, check positions, and place trades. Includes pre-configured IB Gateway and handles OAuth authentication automatically.14161 npm228MIT
- FlicenseNot gradedqualityDmaintenanceConnects AI assistants to Interactive Brokers for intelligent portfolio management, options analysis, risk monitoring, and automated trading strategy suggestions. Enables real-time account tracking, Greeks calculations, option chain analysis, and playbook-based risk adjustments through natural language.5-
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to Interactive Brokers data including contracts, market data, news, fundamentals, and portfolio/account information for LLM workflows and autonomous agents.19BSD 3-Clause
- AlicenseAqualityDmaintenanceEnables AI agents to trade on Interactive Brokers: check quotes, balance, positions, and execute buy/sell orders (including fractional shares by dollar amount) via the Client Portal API.2015MIT