# 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. |

## 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

```bash
npm install
npm run build
```

Useful development commands:

```bash
npm run dev
npm run typecheck
```

## Run

```bash
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:

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

## MCP Configuration Example

Point your MCP client at the built server entrypoint:

```json
{
  "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.