Interactive Brokers MCP Server

Instructions

Implementation Reference

• ibkr/server.py:134-163 (handler)

  Main MCP tool handler for get_ibkr_contract. Decorated with @mcp.tool(), this function validates parameters and routes to either get_contract_details() or get_option_chain() based on info_type parameter. Returns normalized contract details or option chain metadata.

  @mcp.tool()
  def get_ibkr_contract(
      symbol: str,
      sec_type: str = "STK",
      info_type: Literal["details", "option_chain"] = "details",
      exchange: str = "SMART",
      currency: str = "USD",
  ) -> dict:
      """Fetch contract details or option chain metadata from IBKR."""
  
      def _impl() -> dict:
          from .client import IBKRClient
  
          client = IBKRClient()
          if info_type == "option_chain":
              chain = client.get_option_chain(symbol=symbol.upper(), sec_type=sec_type, exchange=exchange)
              return {"status": "success", "info_type": "option_chain", "chain": chain}
  
          details = client.get_contract_details(
              symbol=symbol.upper(),
              sec_type=sec_type,
              exchange=exchange,
              currency=currency,
          )
          return {"status": "success", "info_type": "details", "contracts": details}
  
      try:
          return _with_stderr_stdout(_impl)
      except Exception as exc:
          return {"status": "error", "error": str(exc)}

• ibkr/client.py:126-141 (helper)

  IBKRClient.get_contract_details() method that wraps the IBKR connection manager and delegates to fetch_contract_details() helper. Handles connection management and account resolution.

  def get_contract_details(
      self,
      symbol: str,
      sec_type: str = "STK",
      exchange: str = "SMART",
      currency: str = "USD",
  ) -> list[dict[str, Any]]:
      with ibkr_shared_lock:
          ib = self._get_account_ib()
          return fetch_contract_details(
              ib,
              symbol=symbol,
              sec_type=sec_type,
              exchange=exchange,
              currency=currency,
          )

• ibkr/client.py:143-151 (helper)

  IBKRClient.get_option_chain() method that wraps the IBKR connection manager and delegates to fetch_option_chain() helper for retrieving option chain metadata.

  def get_option_chain(
      self,
      symbol: str,
      sec_type: str = "STK",
      exchange: str = "SMART",
  ) -> dict[str, Any]:
      with ibkr_shared_lock:
          ib = self._get_account_ib()
          return fetch_option_chain(ib, symbol=symbol, sec_type=sec_type, exchange=exchange)

• ibkr/metadata.py:76-90 (helper)

  fetch_contract_details() implementation that builds a contract object, calls IBKR's reqContractDetails API, and normalizes the response using _normalize_contract_detail().

  def fetch_contract_details(
      ib,
      symbol: str,
      sec_type: str = "STK",
      exchange: str = "SMART",
      currency: str = "USD",
  ) -> list[dict[str, Any]]:
      """Fetch normalized contract details."""
      contract = _build_contract(symbol, sec_type, exchange, currency)
      details = list(ib.reqContractDetails(contract) or [])
      if not details:
          raise IBKRContractError(
              f"No contract details found for symbol={symbol} sec_type={sec_type}"
          )
      return [_normalize_contract_detail(detail) for detail in details]

• ibkr/metadata.py:107-157 (helper)

  fetch_option_chain() implementation that qualifies the underlying contract and calls IBKR's reqSecDefOptParams API to retrieve option chain expirations and strikes, normalized via _normalize_chain().

  def fetch_option_chain(
      ib,
      symbol: str,
      sec_type: str = "STK",
      exchange: str = "SMART",
  ) -> dict[str, Any]:
      """Fetch option chain metadata for STK/FUT underlyings."""
      from ib_async import Stock
  
      sec = str(sec_type or "STK").strip().upper()
      sym = str(symbol or "").strip().upper()
      if not sym:
          raise IBKRContractError("Symbol is required")
  
      if sec == "STK":
          underlying = Stock(sym, exchange, "USD")
          fut_fop_exchange = ""
      elif sec == "FUT":
          underlying = resolve_futures_contract(sym)
          fut_fop_exchange = str(getattr(underlying, "exchange", "") or exchange)
      else:
          raise IBKRContractError(f"Option chain supports STK or FUT underlyings, got {sec}")
  
      qualified = list(ib.qualifyContracts(underlying) or [])
      if not qualified:
          raise IBKRContractError(f"Unable to qualify underlying for option chain: {sym}")
  
      resolved = qualified[0]
      con_id = getattr(resolved, "conId", None)
      if con_id in (None, ""):
          raise IBKRContractError(f"Qualified underlying missing conId for {sym}")
  
      underlying_symbol = str(getattr(resolved, "symbol", sym)).upper()
      if sec == "FUT":
          fut_fop_exchange = str(getattr(resolved, "exchange", "") or fut_fop_exchange or exchange)
  
      chains = list(
          ib.reqSecDefOptParams(
              underlyingSymbol=underlying_symbol,
              futFopExchange=fut_fop_exchange,
              underlyingSecType=sec,
              underlyingConId=int(con_id),
          )
          or []
      )
  
      return {
          "underlying": underlying_symbol,
          "con_id": int(con_id),
          "chains": [_normalize_chain(chain) for chain in chains],
      }