mcp-ibkr

自有的 MCP（模型上下文协议）服务器，用于将 Claude Code 与 Interactive Brokers（IBKR）连接，从 Paper Trading 账户上的 只读 模式开始。

项目状态：12 个阶段中的 12 个已完成。参见“当前状态”部分。

1. 这个项目是什么

Claude Code 与 IBKR 之间的桥梁：Claude Code 启动此服务器，服务器暴露“工具”（带名称和描述的函数），当用户询问账户、持仓或市场信息时，Claude 会使用这些工具。没有任何工具直接与 IBKR 通信：所有工具都通过一个集中式集成层。

Related MCP server: IB Portfolio Tracker MCP Server

2. 架构

Claude Code (cliente MCP)
      │  stdio / JSON-RPC
      v
Servidor MCP (src/server.py)
      │
      v
Tool Registry (src/tools/*)
      │
      v
Capa de integración IBKR (src/ibkr/*)
      │  ib_async → socket TCP
      v
IB Gateway (Paper Trading, puerto 4002)
      │
      v
Interactive Brokers

3. 文件夹结构

mcp-ibkr/
├── src/
│   ├── server.py          # Punto de entrada del servidor MCP
│   ├── ibkr/
│   │   └── connection.py     # UNICO lugar que habla con ib_async / IB Gateway
│   ├── tools/
│   │   ├── registry.py       # Registro central: conecta archivos de herramienta con el servidor
│   │   ├── account/            # Saldo, resumen de cuenta, verificar conexión
│   │   ├── market/              # Precio, cotización, históricos
│   │   ├── positions/            # Posiciones abiertas, P&L
│   │   └── orders/                # Consultar (activa) + crear/cancelar (ACTION, deshabilitadas)
│   ├── config/
│   │   └── settings.py       # Carga .env, rechaza arrancar en config insegura
│   └── utils/
│       └── risk.py            # RiskLevel: READ_ONLY / ACTION
├── tests/
├── .env.example
├── .gitignore
├── .mcp.json          # Registro del servidor para Claude Code (scope project)
├── pyproject.toml      # Configuracion de pytest
├── requirements.txt     # Dependencias exactas (pip freeze)
└── README.md

4. 要求

• Python 3.11+（已在 3.14 上测试）。

• Git。

• curl（用于在第 5 节下载 get-pip.py 以及在第 6 节下载 IB Gateway 安装程序）。

• 已安装 IB Gateway，并已启动 Paper Trading 会话（参见第 6 节）。

5. 安装与配置

cd ~/mcp-ibkr

# Crear entorno virtual aislado para este proyecto
python3 -m venv --without-pip .venv

# Instalar pip dentro del venv (no viene incluido con --without-pip)
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
.venv/bin/python3 /tmp/get-pip.py

# Instalar dependencias del proyecto
.venv/bin/python3 -m pip install -r requirements.txt

# Configuración local (nunca se sube a Git)
cp .env.example .env

关于 requirements.txt 的说明：我们只直接安装 4 个包 （mcp、ib_async、python-dotenv、pytest），但该文件有 更多行，因为 pip freeze 还包含了这些包的依赖项（其依赖项的依赖项）。这很正常——并不意味着项目直接使用所有这些库。

注意：在 Debian/Ubuntu 系统上，python3 -m venv 单独使用可能会失败，如果缺少系统包 python3-venv（可通过 sudo apt install python3-venv 安装）。如果你没有 sudo 权限，--without-pip + 在 venv 内手动安装 pip（上述步骤）的组合也能提供同样隔离的环境，而无需管理员权限。

6. 与 IBKR 连接（Paper Trading）

1. 安装 IB Gateway（官方下载，stable-standalone）：

   curl -o ibgateway-stable-standalone-linux-x64.sh \
     https://download.interactivebrokers.com/installers/ibgateway/stable-standalone/ibgateway-stable-standalone-linux-x64.sh
   chmod u+x ibgateway-stable-standalone-linux-x64.sh
   ./ibgateway-stable-standalone-linux-x64.sh

2. 打开它并明确选择 “Paper Trading”（不是“Live Trading”）登录，使用你的 Paper Trading 用户名/密码。

3. 验证 API 端口是否为 4002（Paper）。你可以这样确认：

   ss -ltnp | grep 4002   # deberia aparecer un proceso "java" escuchando

4. 将 .env.example 复制为 .env（如果尚未完成），如果你的配置不同，请调整值。

为什么这是安全的： src/config/settings.py 拒绝启动 如果 IBKR_PORT 不完全是 4002，并且如果 IBKR_PAPER_TRADING_CONFIRMED 不是 true。此外，连接 （src/ibkr/connection.py）以 readonly=True 打开，这会使 IB Gateway 在 API 层面拒绝任何发送订单的尝试，即使在订单工具存在之前也是如此。

7. Claude Code 配置

服务器已在 .mcp.json（项目根目录）中注册，作用域为 project。这意味着该文件会纳入 Git 版本控制，任何在 Claude Code 中打开此仓库的人都会看到建议的服务器——但 不会自动运行：Claude Code 会将其标记为“Pending approval”，直到你在此文件夹内打开会话并批准它。

cd ~/mcp-ibkr
claude    # al iniciar, Claude Code te preguntará si confías en mcp-ibkr

要随时检查服务器状态：

claude mcp list
claude mcp get mcp-ibkr

如果某天你想移除它：

claude mcp remove mcp-ibkr -s project

8. 可用工具

9. 如何添加 / 修改 / 删除 / 禁用工具

每个工具都是 src/tools/<categoria>/ 内的 一个文件，形式如下（参见 src/tools/account/verificar_conexion_ibkr.py 作为真实示例）：

from mcp.types import ToolAnnotations
from src.utils.risk import RiskLevel

NAME = "mi_herramienta"
DESCRIPTION = "Que hace, cuando usarla, que devuelve, si modifica la cuenta."
ANNOTATIONS = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
ENABLED = True
RISK_LEVEL = RiskLevel.READ_ONLY  # o RiskLevel.ACTION si modifica algo

def mi_herramienta(parametro: str) -> str:
    return "resultado"

函数必须 与 NAME 同名——这样中央注册表（src/tools/registry.py）会自动找到它。如果 RISK_LEVEL 是 ACTION，除了 ENABLED = True 之外，还需要在 .env 中设置 IBKR_ENABLE_ACTION_TOOLS=true（参见第 11 节）——两个独立的键，这是有意的。

关于 ANNOTATIONS：destructiveHint 和 idempotentHint 仅在 readOnlyHint=False 时有意义（MCP 规范如此说明）——因此对于只读工具，只需 readOnlyHint 和 openWorldHint。只有当 RISK_LEVEL 为 ACTION 时才添加它们，如 src/tools/orders/crear_orden.py 中所示。

添加工具

1. 在相应类别中创建文件（或创建新类别，见下文）。

2. 将文件名（不带 .py）添加到该类别的 __init__.py 中的 TOOLS 列表。

3. 重启 Claude Code 会话以使其被拾取（Claude Code 在服务器启动时只读取一次工具；claude mcp list 只查询连接状态，不重新加载任何内容）。

修改工具

直接编辑其文件——DESCRIPTION、函数参数、内部逻辑等。无需修改 registry.py。

删除工具

删除文件并从其类别的 __init__.py 中的 TOOLS 中移除其名称。

禁用工具（不删除）

在其文件中设置 ENABLED = False。registry.py 会自动跳过它。

创建新类别

创建文件夹 src/tools/<categoria>/，其中包含一个定义 TOOLS: list[str] = [...] 的 __init__.py，并将类别名称添加到 src/tools/registry.py 中的 CATEGORIES。

10. 测试

cd ~/mcp-ibkr
.venv/bin/python3 -m pytest tests/ -v

• tests/test_server.py — 服务器启动并暴露预期的工具（与 Claude Code 连接时看到的相同）；只读工具不设置不适用的注解；如果 IBKR 不可用，每个工具都会返回友好的消息，而不是让异常逃逸。

• tests/test_settings.py — 配置 拒绝 非 4002 的端口以及缺少 IBKR_PAPER_TRADING_CONFIRMED。

• tests/test_connection.py — 连接层序列化连接尝试（使用模拟的 IBKR，不需要真实的 Gateway）：如果两个工具几乎同时被调用，永远不会有两个连接尝试并行运行。

• tests/test_risk_system.py — ACTION 工具（crear_orden、cancelar_orden）默认 不注册，订单验证（数量、类型、价格）拒绝无效参数。

• tests/test_ibkr_integration.py — 针对 IB Gateway 的真实连接。如果 Gateway 未运行，此测试会 跳过（不会失败）——这是预期的，不是项目错误。

所有与订单相关的测试要么隔离使用 validar_parametros_orden（不接触 IBKR），要么依赖于 crear_orden 默认被禁用：此项目的任何测试都不会发送真实订单，即使在 Paper Trading 中也是如此。

11. 从 Paper Trading 到 Live Trading

⚠️ 此项目尚不支持 Live Trading，且 crear_orden/cancelar_orden 默认禁用。 以下是对安全层的解释，并非邀请你未经思考就启用它们。

有 三个独立层 防止意外发送真实订单：

1. 强制端口 4002 — src/config/settings.py 拒绝启动 如果 IBKR_PORT 不完全是 Paper Trading 的端口。此版本的项目 没有任何代码路径使用端口 4001（Live）。

2. ACTION 工具的双重密钥 — crear_orden 和 cancelar_orden 需要在其自身文件中设置 ENABLED = True 并且 在 .env 中设置 IBKR_ENABLE_ACTION_TOOLS=true。两者默认均未激活。两者仅在服务器启动时读取：如果服务器已在运行，更改它们需要重启 Claude Code 会话才能生效。

3. API 级别的只读连接 — 只要 IBKR_ENABLE_ACTION_TOOLS 为 false，src/ibkr/connection.py 就会以 readonly=True 连接：即使有人设法绕过前两层，IB Gateway 也会拒绝任何订单。

如果将来你决定 在 Paper Trading 中启用订单发送，路径将是：审查并加强 src/tools/orders/crear_orden.py 中的验证，在 .env 中设置 IBKR_ENABLE_ACTION_TOOLS=true，并在订单文件中设置 ENABLED = True。真正的 Live Trading 支持在此项目中既未实现也未计划——在考虑之前，需要进行完全独立的安全审查。

12. 当前状态

• 阶段 1 — 架构与概念

• 阶段 2 — 项目最小结构

• 阶段 3 — 开发环境

• 阶段 4 — 最小 MCP 服务器

• 阶段 5 — 将 Claude Code 与 MCP 连接

• 阶段 6 — 第一个测试工具

• 阶段 7 — 与 IB Gateway 连接（Paper Trading）

• 阶段 8 — 查询工具

• 阶段 9 — 验证与风险系统

• 阶段 10 — 订单工具（已锁定）

• 阶段 11 — 完整测试

• 阶段 12 — 最终文档