interactive-brokers-mcp 0.1.0__tar.gz

interactive_brokers_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+venv/
+__pycache__/
+*.pyc
+.DS_Store
+.env
+cache/
+dist/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/

interactive_brokers_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Chien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

interactive_brokers_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: interactive-brokers-mcp
+Version: 0.1.0
+Summary: MCP server for Interactive Brokers Gateway — 6 tools for market data and account access via Claude
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: certifi
+Requires-Dist: fastmcp
+Requires-Dist: ib-async
+Requires-Dist: nest-asyncio
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: zstandard
+Description-Content-Type: text/markdown
+
+# ibkr-mcp
+
+MCP server for Interactive Brokers Gateway — 6 tools for market data and account access via Claude.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_ibkr_market_data` | Historical OHLCV bars for any contract |
+| `get_ibkr_positions` | Current portfolio positions and P&L |
+| `get_ibkr_account` | Account summary (balances, margin, NAV) |
+| `get_ibkr_contract` | Contract lookup and details |
+| `get_ibkr_option_prices` | Option chain pricing |
+| `get_ibkr_snapshot` | Real-time quote snapshot |
+
+## Install
+
+```bash
+pip install ibkr-mcp
+```
+
+## Prerequisites
+
+- [IB Gateway](https://www.interactivebrokers.com/en/trading/ibgateway-stable.php) or TWS running
+- API access enabled in Gateway/TWS settings
+- Host/port/client ID matching your environment variables
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `IBKR_GATEWAY_HOST` | `127.0.0.1` | Gateway hostname |
+| `IBKR_GATEWAY_PORT` | `7496` | Gateway port |
+| `IBKR_CLIENT_ID` | `1` | API client ID |
+| `IBKR_TIMEOUT` | `10` | Connection timeout (seconds) |
+| `IBKR_READONLY` | `false` | Read-only mode |
+| `IBKR_AUTHORIZED_ACCOUNTS` | | Comma-separated account whitelist |
+| `IBKR_CACHE_DIR` | | Optional cache directory override |
+
+The package auto-loads `.env` from the package directory and parent.
+
+## Usage
+
+### Claude Code
+
+```bash
+claude mcp add ibkr-mcp -- ibkr-mcp
+```
+
+Or in `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "ibkr-mcp": {
+      "type": "stdio",
+      "command": "ibkr-mcp"
+    }
+  }
+}
+```
+
+### Standalone
+
+```bash
+ibkr-mcp          # via installed entry point
+python -m ibkr.server   # via module
+```
+
+## License
+
+MIT

interactive_brokers_mcp-0.1.0/README.md

@@ -0,0 +1,72 @@
+# ibkr-mcp
+
+MCP server for Interactive Brokers Gateway — 6 tools for market data and account access via Claude.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_ibkr_market_data` | Historical OHLCV bars for any contract |
+| `get_ibkr_positions` | Current portfolio positions and P&L |
+| `get_ibkr_account` | Account summary (balances, margin, NAV) |
+| `get_ibkr_contract` | Contract lookup and details |
+| `get_ibkr_option_prices` | Option chain pricing |
+| `get_ibkr_snapshot` | Real-time quote snapshot |
+
+## Install
+
+```bash
+pip install ibkr-mcp
+```
+
+## Prerequisites
+
+- [IB Gateway](https://www.interactivebrokers.com/en/trading/ibgateway-stable.php) or TWS running
+- API access enabled in Gateway/TWS settings
+- Host/port/client ID matching your environment variables
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `IBKR_GATEWAY_HOST` | `127.0.0.1` | Gateway hostname |
+| `IBKR_GATEWAY_PORT` | `7496` | Gateway port |
+| `IBKR_CLIENT_ID` | `1` | API client ID |
+| `IBKR_TIMEOUT` | `10` | Connection timeout (seconds) |
+| `IBKR_READONLY` | `false` | Read-only mode |
+| `IBKR_AUTHORIZED_ACCOUNTS` | | Comma-separated account whitelist |
+| `IBKR_CACHE_DIR` | | Optional cache directory override |
+
+The package auto-loads `.env` from the package directory and parent.
+
+## Usage
+
+### Claude Code
+
+```bash
+claude mcp add ibkr-mcp -- ibkr-mcp
+```
+
+Or in `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "ibkr-mcp": {
+      "type": "stdio",
+      "command": "ibkr-mcp"
+    }
+  }
+}
+```
+
+### Standalone
+
+```bash
+ibkr-mcp          # via installed entry point
+python -m ibkr.server   # via module
+```
+
+## License
+
+MIT

interactive_brokers_mcp-0.1.0/ibkr/__init__.py

@@ -0,0 +1,55 @@
+"""IBKR provider package.
+
+Agent orientation:
+    Public package entrypoint for IBKR integration.
+    For market data/account operations start with ``ibkr.client.IBKRClient``;
+    for compatibility wrappers used by other modules start with ``ibkr.compat``.
+"""
+
+from .client import IBKRClient
+from .market_data import IBKRMarketDataClient
+from .compat import (
+    fetch_ibkr_bond_monthly_close,
+    fetch_ibkr_daily_close_futures,
+    fetch_ibkr_flex_trades,
+    fetch_ibkr_fx_monthly_close,
+    fetch_ibkr_monthly_close,
+    fetch_ibkr_option_monthly_mark,
+    get_futures_currency,
+    get_ibkr_futures_exchanges,
+    get_ibkr_futures_fmp_map,
+)
+from .exceptions import (
+    IBKRConnectionError,
+    IBKRContractError,
+    IBKRDataError,
+    IBKREntitlementError,
+    IBKRAccountError,
+    IBKRNoDataError,
+    IBKRTimeoutError,
+)
+from .profiles import InstrumentProfile, get_profile, get_profiles
+
+__all__ = [
+    "IBKRClient",
+    "IBKRMarketDataClient",
+    "fetch_ibkr_monthly_close",
+    "fetch_ibkr_daily_close_futures",
+    "fetch_ibkr_fx_monthly_close",
+    "fetch_ibkr_bond_monthly_close",
+    "fetch_ibkr_option_monthly_mark",
+    "fetch_ibkr_flex_trades",
+    "get_ibkr_futures_fmp_map",
+    "get_ibkr_futures_exchanges",
+    "get_futures_currency",
+    "InstrumentProfile",
+    "get_profile",
+    "get_profiles",
+    "IBKRDataError",
+    "IBKRConnectionError",
+    "IBKRContractError",
+    "IBKRNoDataError",
+    "IBKREntitlementError",
+    "IBKRAccountError",
+    "IBKRTimeoutError",
+]

interactive_brokers_mcp-0.1.0/ibkr/_logging.py

@@ -0,0 +1,23 @@
+"""IBKR package-local logging shims with monorepo fallback behavior."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+
+def _make_fallback_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(f"ibkr.{name}")
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stderr)
+        handler.setFormatter(logging.Formatter("%(asctime)s [%(name)s] %(levelname)s: %(message)s"))
+        logger.addHandler(handler)
+    logger.setLevel(logging.INFO)
+    return logger
+
+
+try:
+    from utils.logging import portfolio_logger, trading_logger
+except Exception:
+    portfolio_logger = _make_fallback_logger("portfolio")
+    trading_logger = _make_fallback_logger("trading")

interactive_brokers_mcp-0.1.0/ibkr/_types.py

@@ -0,0 +1,25 @@
+"""Shared instrument metadata types vendored for ibkr package portability."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+InstrumentType = Literal["equity", "option", "futures", "fx", "fx_artifact", "bond", "unknown"]
+
+_VALID_INSTRUMENT_TYPES = {
+    "equity",
+    "option",
+    "futures",
+    "fx",
+    "fx_artifact",
+    "bond",
+    "unknown",
+}
+
+
+def coerce_instrument_type(value: Any, default: InstrumentType = "equity") -> InstrumentType:
+    """Normalize external instrument strings to the supported instrument type enum."""
+    normalized = str(value or "").strip().lower()
+    if normalized in _VALID_INSTRUMENT_TYPES:
+        return normalized  # type: ignore[return-value]
+    return default

interactive_brokers_mcp-0.1.0/ibkr/_vendor.py

@@ -0,0 +1,23 @@
+"""Lightweight helpers vendored from trading_analysis for ibkr portability."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def safe_float(value: Any, default: float = 0.0) -> float:
+    """Safely convert value to float."""
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return default
+
+
+def normalize_strike(strike: Any) -> str:
+    """Canonical strike string: 30.0->"30", 2.5->"2p5", 2.50->"2p5"."""
+    val = float(strike)
+    if val == int(val):
+        return str(int(val))
+    return f"{val:g}".replace(".", "p")

interactive_brokers_mcp-0.1.0/ibkr/account.py

@@ -0,0 +1,186 @@
+"""Account-level IBKR data helpers."""
+
+from __future__ import annotations
+
+import math
+import time
+from typing import Any
+
+import pandas as pd
+
+from .exceptions import IBKRTimeoutError
+
+
+_POSITION_COLUMNS = [
+    "account",
+    "symbol",
+    "sec_type",
+    "currency",
+    "exchange",
+    "con_id",
+    "position",
+    "avg_cost",
+]
+
+_SUMMARY_TAGS = {
+    "NetLiquidation": "net_liquidation",
+    "TotalCashValue": "total_cash_value",
+    "BuyingPower": "buying_power",
+    "GrossPositionValue": "gross_position_value",
+    "MaintMarginReq": "maint_margin_req",
+    "AvailableFunds": "available_funds",
+    "ExcessLiquidity": "excess_liquidity",
+    "SMA": "sma",
+}
+
+
+def _safe_float(value: Any) -> float | None:
+    try:
+        if value is None:
+            return None
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _is_not_nan(value: Any) -> bool:
+    as_float = _safe_float(value)
+    if as_float is None:
+        return False
+    return not math.isnan(as_float)
+
+
+def _ib_sleep(ib, seconds: float) -> None:
+    try:
+        sleep_fn = getattr(ib, "sleep", None)
+        if callable(sleep_fn):
+            sleep_fn(seconds)
+        else:
+            time.sleep(seconds)
+    except Exception:
+        time.sleep(seconds)
+
+
+def _wait_for_pnl_ready(ib, pnl_obj, *, timeout_seconds: float, poll_interval: float) -> None:
+    deadline = time.monotonic() + timeout_seconds
+    while time.monotonic() < deadline:
+        if _is_not_nan(getattr(pnl_obj, "dailyPnL", None)):
+            return
+        _ib_sleep(ib, poll_interval)
+    raise IBKRTimeoutError("Timed out waiting for IBKR PnL update")
+
+
+def fetch_positions(ib, account_id: str | None = None) -> pd.DataFrame:
+    """Fetch IBKR positions and normalize to DataFrame."""
+    ib.reqPositions()
+    positions = list(ib.positions() or [])
+
+    rows: list[dict[str, Any]] = []
+    for pos in positions:
+        acct = getattr(pos, "account", None)
+        if account_id and acct != account_id:
+            continue
+        contract = getattr(pos, "contract", None)
+        rows.append(
+            {
+                "account": acct,
+                "symbol": getattr(contract, "symbol", None) if contract else None,
+                "sec_type": getattr(contract, "secType", None) if contract else None,
+                "currency": getattr(contract, "currency", None) if contract else None,
+                "exchange": getattr(contract, "exchange", None) if contract else None,
+                "con_id": getattr(contract, "conId", None) if contract else None,
+                "position": _safe_float(getattr(pos, "position", None)),
+                "avg_cost": _safe_float(getattr(pos, "avgCost", None)),
+            }
+        )
+
+    if not rows:
+        return pd.DataFrame(columns=_POSITION_COLUMNS)
+    frame = pd.DataFrame(rows, columns=_POSITION_COLUMNS)
+    return frame.sort_values(["account", "symbol"], na_position="last").reset_index(drop=True)
+
+
+def fetch_account_summary(ib, account_id: str | None = None) -> dict[str, float]:
+    """Fetch account summary values with USD-only tag normalization."""
+    account_values = list(ib.accountValues(account=account_id) or [])
+    if not account_values:
+        ib.reqAccountUpdates(account=account_id)
+        account_values = list(ib.accountValues(account=account_id) or [])
+
+    summary: dict[str, float] = {}
+    for av in account_values:
+        if account_id and getattr(av, "account", None) not in (None, "", account_id):
+            continue
+        if getattr(av, "currency", None) != "USD":
+            continue
+        key = _SUMMARY_TAGS.get(getattr(av, "tag", None))
+        if key is None:
+            continue
+        val = _safe_float(getattr(av, "value", None))
+        if val is None:
+            continue
+        summary[key] = val
+
+    return summary
+
+
+def fetch_pnl(
+    ib,
+    account_id: str,
+    *,
+    timeout_seconds: float = 5.0,
+    poll_interval: float = 0.1,
+) -> dict[str, float | str | None]:
+    """Fetch account-level PnL via streaming subscription with timeout polling."""
+    pnl_obj = ib.reqPnL(account_id, modelCode="")
+    try:
+        _wait_for_pnl_ready(
+            ib,
+            pnl_obj,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+        )
+        return {
+            "account_id": account_id,
+            "daily_pnl": _safe_float(getattr(pnl_obj, "dailyPnL", None)),
+            "unrealized_pnl": _safe_float(getattr(pnl_obj, "unrealizedPnL", None)),
+            "realized_pnl": _safe_float(getattr(pnl_obj, "realizedPnL", None)),
+        }
+    finally:
+        try:
+            ib.cancelPnL(account_id, modelCode="")
+        except Exception:
+            pass
+
+
+def fetch_pnl_single(
+    ib,
+    account_id: str,
+    con_id: int,
+    *,
+    timeout_seconds: float = 5.0,
+    poll_interval: float = 0.1,
+) -> dict[str, float | int | str | None]:
+    """Fetch contract-level PnL via streaming subscription with timeout polling."""
+    pnl_obj = ib.reqPnLSingle(account_id, modelCode="", conId=int(con_id))
+    try:
+        _wait_for_pnl_ready(
+            ib,
+            pnl_obj,
+            timeout_seconds=timeout_seconds,
+            poll_interval=poll_interval,
+        )
+        return {
+            "account_id": account_id,
+            "con_id": int(con_id),
+            "daily_pnl": _safe_float(getattr(pnl_obj, "dailyPnL", None)),
+            "unrealized_pnl": _safe_float(getattr(pnl_obj, "unrealizedPnL", None)),
+            "realized_pnl": _safe_float(getattr(pnl_obj, "realizedPnL", None)),
+            "position": _safe_float(getattr(pnl_obj, "position", None)),
+            "value": _safe_float(getattr(pnl_obj, "value", None)),
+        }
+    finally:
+        try:
+            ib.cancelPnLSingle(account_id, modelCode="", conId=int(con_id))
+        except Exception:
+            pass