Skip to main content
Glama
ibkr-mcp

ibkr-mcp

ibkr-mcp

ibkr-mcp is a read-only MCP server for Interactive Brokers IBKR Gateway or TWS. It connects to an already running socket API session and exposes account, contract, execution, and historical-data queries to MCP clients over stdio.

The server does not implement any order-entry operations. There are no tools for placing, modifying, or cancelling orders.

What It Exposes

Tool

Purpose

ibkr_status

Confirm connectivity and return IBKR server time.

ibkr_accounts

List managed accounts visible to the current login.

ibkr_account_summary

Fetch account summary values such as cash, buying power, and margin.

ibkr_positions

List open positions across accessible accounts.

ibkr_open_orders

List currently open orders visible to the session.

ibkr_executions

Fetch execution reports with optional account, symbol, side, and time filters.

ibkr_search_contracts

Search contracts by ticker or company name.

ibkr_contract_details

Resolve a partial contract definition into concrete IBKR contract details.

ibkr_historical_bars

Fetch read-only historical bars for a contract.

Related MCP server: IBKR MCP Server

Safety Model

  • Every registered MCP tool is read-only.

  • The server never calls IBKR APIs for order placement, modification, or cancellation.

  • A local process lock prevents duplicate ibkr-mcp instances from starting against the same IBKR_HOST / IBKR_PORT / IBKR_CLIENT_ID combination.

  • You should still enable IBKR's own Read-Only API setting if you want Gateway- or TWS-level enforcement as a second guardrail.

Prerequisites

  • Node.js and npm

  • A running IBKR Gateway or TWS session

  • Socket API access enabled in that IBKR session

In IBKR Gateway or TWS:

  1. Open the API settings page.

  2. Enable ActiveX and Socket Clients.

  3. Set the socket port to the value you want this server to use.

  4. Enable Read-Only API if you want IBKR to enforce read-only access too.

  5. Allow 127.0.0.1 or your MCP host in trusted IPs if your IBKR configuration requires it.

The server default is IBKR_PORT=4002, which matches the common IBKR Gateway paper-trading setup. If your session uses a different port, set IBKR_PORT explicitly.

Install

npm install
npm run build

Useful development commands:

npm run dev
npm run typecheck

Run

IBKR_HOST=127.0.0.1 \
IBKR_PORT=4002 \
IBKR_CLIENT_ID=19191 \
npm start

IBKR_CLIENT_ID must be unique for the API client session you want to open. Run exactly one ibkr-mcp process per IBKR_HOST / IBKR_PORT / IBKR_CLIENT_ID.

If your MCP client launches this server for you, do not also leave a separate npm start process running against the same target. The server will fail fast if another instance already holds the same lock.

Configuration

Variable

Default

Description

IBKR_HOST

127.0.0.1

Hostname of the IBKR Gateway or TWS socket API endpoint.

IBKR_PORT

4002

Socket API port.

IBKR_CLIENT_ID

19191

API client ID used when connecting to IBKR.

IBKR_TIMEOUT_MS

10000

Request timeout for IBKR API calls.

IBKR_ACCOUNT_GROUP

All

Default account group for ibkr_account_summary.

IBKR_ACCOUNT_SUMMARY_TAGS

conservative defaults

Optional comma-separated override for summary fields.

Default account summary tags:

AccountType,NetLiquidation,TotalCashValue,SettledCash,BuyingPower,AvailableFunds,ExcessLiquidity,GrossPositionValue,InitMarginReq,MaintMarginReq,DayTradesRemaining

MCP Configuration Example

Point your MCP client at the built server entrypoint:

{
  "mcpServers": {
    "ibkr": {
      "command": "node",
      "args": ["/absolute/path/to/ibkr-mcp/dist/index.js"],
      "env": {
        "IBKR_HOST": "127.0.0.1",
        "IBKR_PORT": "4002",
        "IBKR_CLIENT_ID": "19191"
      }
    }
  }
}

This project uses stdio transport. That means each MCP client normally starts its own server process. If you need multiple clients to share one IBKR session, move to a shared daemon or network transport rather than launching separate stdio instances.

Usage Notes

  • ibkr_executions accepts either time in raw IB format (YYYYMMDD HH:mm:ss) or since in RFC3339 form, but not both.

  • ibkr_search_contracts is useful for discovery; ibkr_contract_details is the better follow-up when you need a specific contract definition for downstream calls.

  • For stock and option lookups, the server infers SMART as the default exchange when appropriate. For cash pairs, it infers IDEALPRO.

  • Historical data, executions, and some contract lookups still depend on the permissions attached to the logged-in IBKR user.

Troubleshooting

  • Connection failures usually mean the IBKR session is not running, the socket API is disabled, the port is wrong, or the client ID is already in use.

  • Duplicate-process errors mean another ibkr-mcp process is already running with the same host, port, and client ID combination.

  • Empty or incomplete market-data responses often point to IBKR permissions, exchange entitlements, or an underspecified contract.

  • This server does not launch IBKR Gateway or TWS. It only connects to an existing API endpoint.

Available Tools

9 tools
ibkr_accountsA
Read-only

List managed IBKR accounts visible to the current Gateway login.

Inputs: no named parameters.

ibkr_account_summaryA
Read-only

Return account summary values such as net liquidation, cash, buying power, and margin.

Inputs: tags, group.

ibkr_contract_detailsB
Read-only

Resolve an IBKR contract definition and return matching contract details.

Inputs: contract (required), limit.

ibkr_executionsB
Read-only

Return execution reports using optional filters such as account, symbol, side, or time.

Inputs: side, time, since, symbol, +4 more.

ibkr_historical_barsA
Read-only

Fetch read-only historical bars for a contract from IBKR Gateway.

Inputs: contract (required), useRTH, barSize, formatDate, +3 more.

ibkr_open_ordersA
Read-only

List currently open orders visible to the Gateway session. This server does not place, modify, or cancel orders.

Inputs: no named parameters.

ibkr_positionsA
Read-only

List open positions across all accessible IBKR accounts.

Inputs: no named parameters.

ibkr_search_contractsA
Read-only

Search IBKR contracts by ticker or company name and return matching instrument descriptors.

Inputs: pattern (required), limit.

ibkr_statusA
Read-only

Confirm read-only connectivity to the configured IBKR Gateway session and return server time.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool maps to a distinct IBKR resource: accounts, positions, account summary, open orders, executions, contract search, contract details, historical bars, and gateway status. Even the two contract tools are clearly separated as discovery versus detail resolution.

    Naming Consistency4/5

    All tools share a consistent lowercase ibkr_ prefix and mostly use noun-style resource names such as ibkr_positions and ibkr_account_summary. The one action-style name, ibkr_search_contracts, is a minor deviation from an otherwise predictable pattern.

    Tool Count5/5

    Nine tools is a well-scoped size for a read-only IBKR integration. Each tool covers a distinct data need without redundant overlap or unnecessary extras.

    Completeness4/5

    The set covers the core read-only brokerage workflow: accounts, positions, summary, orders, executions, contract discovery, and historical bars. A real-time quote or market data snapshot tool would round it out, but this is a minor gap given the read-only orientation.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      C
      quality
      D
      maintenance
      An MCP server that provides an interface for the Interactive Brokers API via the ib_async library. It enables users to manage accounts, access real-time and historical market data, and execute or monitor trades through TWS or IB Gateway.
      33
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for Interactive Brokers, enabling account management, trading operations, and market data queries.
      8
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for Interactive Brokers that exposes market data, positions, and account info as MCP tools.
      8
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      MCP server for Interactive Brokers via IB Gateway, enabling read access to account data and trading capabilities for paper accounts.
      11
      -