# IBKR Portfolio Builder

Connects Interactive Brokers screeners and portfolio metrics to an agent for top-down equity research. Helps screen stocks and ETFs based on strategy tags.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 19
- Author: adwiteeymauriya
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/adwiteeymauriya/ibkr-portfolio-builder-mcp
- Updated: 2026-06-08
- HTML: https://affpapa.org/en/nevibecode/mcp/ibkr-portfolio-builder

## What it does

The server connects clients to a sibling `ib-gateway` service via streaming HTTP at `/mcp`. It packages a structured catalog of 468 IBKR scan codes across 16 categories, labeled with 28 strategy tags such as dividends or value. Instead of guessing raw scanner codes, the agent queries mapped filters, applicable instruments, and inverse pairs.

The toolset includes nine read-only tools for portfolio metrics and OHLCV history, alongside five tools for news feeds and market scans. Order placement is blocked by design. The underlying `ib-gateway` runs with `READ_ONLY_API=yes` to prevent unattended trades.

Authentication supports both OAuth 2.1 with PKCE and a static bearer token. Client registrations and active sessions live in memory, meaning container restarts reset authorization state.

## Requirements
- Remote server: `https://{ibkr_mcp_host}/mcp`

## Install

### Claude Code (native platform)

1. **Template address**
- The server address is a template: replace {…} or […] with your own values

2. **Platform CLI: remote server**
```bash
claude mcp add --transport http ibkr-portfolio-builder-mcp https://{ibkr_mcp_host}/mcp
```

### Codex

1. **Template address**
- The server address is a template: replace {…} or […] with your own values

2. **Platform CLI: remote server**
```bash
codex mcp add ibkr-portfolio-builder --url https://{ibkr_mcp_host}/mcp
```

### Cursor

1. **Template address**
- The server address is a template: replace {…} or […] with your own values

2. **Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "ibkr-portfolio-builder": {
            "url": "https://{ibkr_mcp_host}/mcp"
        }
    }
}
```

### GitHub Copilot

1. **Template address**
- The server address is a template: replace {…} or […] with your own values

2. **Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "ibkr-portfolio-builder": {
            "type": "http",
            "url": "https://{ibkr_mcp_host}/mcp"
        }
    }
}
```

### Gemini CLI

1. **Template address**
- The server address is a template: replace {…} or […] with your own values

2. **Platform CLI: remote server**
```bash
gemini mcp add -t http ibkr-portfolio-builder https://{ibkr_mcp_host}/mcp
```

## When to use it
- screen US equities and ETFs using typed IBKR market scans
- review headlines and upcoming events across subscribed news providers
- inspect portfolio cash balances, open orders, and unrealized profit
- pull OHLCV historical price bars across various timeframes

## Example prompts
- Run a scan for US large-cap value stocks with low debt and high dividend yield
- Check recent news headlines for candidate symbols using ib_news_for_symbol
- Show open positions and total cash value on my Interactive Brokers account

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583
- [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458
- [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814
- [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188
- [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md