<div align="center">

# ibkr-mcp

[![License](https://img.shields.io/badge/LICENSE-MIT-5C9E31?style=for-the-badge)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-model%20context%20protocol-6E56CF?style=for-the-badge)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/PYTHON-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org)
[![Built by](https://img.shields.io/badge/BUILT%20BY-JEAN%20GALEA-8A2BE2?style=for-the-badge)](https://github.com/jgalea)

**A read-only-by-default MCP server for Interactive Brokers — account, positions, PnL, market data, and full trade history from a local TWS / IB Gateway session.**

</div>

## What it is

`ibkr-mcp` exposes your Interactive Brokers account to any [Model Context Protocol](https://modelcontextprotocol.io) client (Claude Code, Claude Desktop, and others) through a locally running Trader Workstation or IB Gateway, using the [ib_async](https://github.com/ib-api-reloaded/ib_async) library.

No credentials pass through this server. You log in to TWS or IB Gateway as usual, and `ibkr-mcp` attaches to its API socket on `127.0.0.1`. By default it is read-only: no order tools exist, and the only outbound network call it can make is the optional Flex history fetch, pinned to `interactivebrokers.com`.

## Tools

Read-only (always available):

- `list_accounts`, `get_account_summary`, `get_positions`, `get_portfolio`, `get_pnl`
- `get_quote`, `get_historical_data`, `lookup_contract`, `search_contracts`
- `get_open_orders`, `get_executions`
- `review_positions` — flags open positions past a loss threshold for a deliberate "thesis changed or just the price?" review
- `get_trade_history`, `get_cash_transactions`, `get_history_coverage` (see [Historical activity](#historical-activity))

Trading (only registered when `IBKR_ENABLE_TRADING=true`):

- `preview_order` — a what-if that returns margin and commission impact and places nothing
- `place_order` — market or limit orders, with quantity, notional, and rate caps
- `cancel_order` — cancels an open order (by default only orders this server placed)

## Requirements

- [uv](https://docs.astral.sh/uv/) for dependency management.
- TWS or IB Gateway, running and logged in, with the API enabled: Configure > Settings > API > "Enable ActiveX and Socket Clients". Keep "Read-Only API" checked unless you deliberately enable trading.
- Ports: TWS live `7496`, TWS paper `7497`, Gateway live `4001`, Gateway paper `4002`.

## Install

```sh
git clone https://github.com/jgalea/ibkr-mcp.git
cd ibkr-mcp
uv sync --locked
```

Register with Claude Code (run from the cloned directory):

```sh
claude mcp add ibkr --env IBKR_PORT=4001 -- uv --directory "$(pwd)" run ibkr-mcp
```

Or with Claude Desktop, in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ibkr": {
      "command": "uv",
      "args": ["--directory", "/path/to/ibkr-mcp", "run", "ibkr-mcp"],
      "env": { "IBKR_PORT": "4001" }
    }
  }
}
```

## Configuration

| Variable | Default | Notes |
|---|---|---|
| `IBKR_HOST` | `127.0.0.1` | TWS / Gateway host |
| `IBKR_PORT` | `7497` | Match your TWS / Gateway mode |
| `IBKR_CLIENT_ID` | `23` | Unique per API client (must be ≥ 1) |
| `IBKR_TIMEOUT` | `10` | Connect and request timeout, seconds |
| `IBKR_MARKET_DATA_TYPE` | `3` | 1 live, 2 frozen, 3 delayed, 4 delayed-frozen |
| `IBKR_ENABLE_TRADING` | unset | `true` / `1` / `yes` registers the order tools |
| `IBKR_MAX_ORDER_QUANTITY` | `1000` | Hard cap on units per order (ceiling 1,000,000) |
| `IBKR_MAX_ORDER_VALUE` | `50000` | Cap on order notional (ceiling 10,000,000). Exact for limit orders; for market orders it is checked against a pre-submit snapshot price, so a fast-moving fill can exceed it |
| `IBKR_ORDERS_PER_MINUTE` | `6` | Aggregate order rate limit across concurrent calls |
| `IBKR_ALLOW_EXTERNAL_CANCEL` | unset | `true` lets `cancel_order` cancel orders not placed by this server |

## Security model

Trading is gated in three independent layers:

- No order tools are registered unless `IBKR_ENABLE_TRADING=true`, so a client cannot call what does not exist.
- In read-only mode every account-mutating call in the underlying library is stubbed out inside the process, so no code path can transmit an order.
- TWS / Gateway's own "Read-Only API" setting rejects order requests at the gateway. Keep it checked unless you enable trading. (The library's `readonly` connect flag only skips fetching order state; it is not enforcement on its own.)

Other properties:

- Transport is stdio and pinned; it cannot be promoted to a network listener by an environment variable or a stray `.env`.
- The IB API protocol is cleartext TCP. Keep `IBKR_HOST` on localhost; tunnel over SSH if you must reach a remote gateway.
- Do not run with `INFO`/`DEBUG` logging: the HTTP client logs request URLs at `INFO`, and Flex request URLs carry your token.
- Tool output (account IDs, balances, positions) flows into whatever model your MCP host uses. Be deliberate about which host you connect.

When trading is enabled, test against a paper account (port `7497` / `4002`) first, and keep TWS's precautionary order settings on.

## Historical activity

The Gateway socket only exposes current-day executions. `get_trade_history` and `get_cash_transactions` pull full account history (trades, dividends, interest, deposits, fees) from IBKR's Flex Web Service over HTTPS, and cache it in a local SQLite archive (`~/.ibkr-mcp/archive.db`, owner-only) so rows never age out of the rolling Flex window.

One-time setup in Client Portal:

1. Performance & Reports > Flex Queries > new Activity Flex Query. Include the Trades and Cash Transactions sections, period "Last 365 Calendar Days", format XML. Note the numeric Query ID.
2. On the same page, under Flex Web Service Configuration, enable it and generate a token.
3. Store the token outside your config, for example in the macOS Keychain, then point the server at it:

| Variable | Notes |
|---|---|
| `IBKR_FLEX_QUERY_ID` | Numeric ID of your Activity Flex Query (or `IBKR_FLEX_QUERY_IDS`, comma-separated, for several) |
| `IBKR_FLEX_TOKEN_CMD` | A command whose stdout is the token, e.g. `security find-generic-password -s ibkr-flex-token -w` |
| `IBKR_FLEX_TOKEN` | The token itself (fallback; prefer `IBKR_FLEX_TOKEN_CMD` so it stays out of config files) |

### Backfilling history older than 365 days

A Flex query reaches at most the trailing 365 days. To seed the archive with older history, export Activity Statements (Client Portal > Performance & Reports > Statements > Activity Statement, Custom Date Range, up to 365 days per file, Download CSV) and import them:

```sh
uv run python -m ibkr_mcp.importer /path/to/activity_statement.csv
```

Imports are deduplicated, so re-running is safe. `get_history_coverage` reports the archived span.

## Development

```sh
uv run pytest
uv run ruff check src tests
```

## Disclaimer

Not affiliated with or endorsed by Interactive Brokers. Provided as-is under the MIT license, with no warranty. You are responsible for any orders placed through it and for keeping the trading gates configured as you intend. Nothing here is investment advice.

## License

[MIT](LICENSE)