使用说明

ibkr mcp

A. 模型上下文协议（MCP）服务器 盈透证券.将任何兼容MCP的AI代理连接到TWS或IB网关，并通过自然语言访问80多种工具——市场数据、订单管理、账户监控、风险分析、新闻和扫描。

特性

80+MCP工具 涵盖8个类别（合同、市场数据、订单、账户、风险、新闻、扫描仪、管理员）
交易前护栏 --最大数量、最大名义损失、每日损失限额、交易品种允许/拒绝列表、只读模式
流媒体支持 --通过MCP通知实时市场数据、订单状态、账户更新
结构化信封响应 --每个响应都包含在 { success, data, error, meta } 包含请求ID、时间戳和延迟
使用回退重新连接 --指数回退+抖动，自动恢复订阅
速率限制 --令牌桶的速度为45请求/秒（遵守IB的50毫秒/秒限制）
全TypeScript严格模式 — noUncheckedIndexedAccess, noUnusedLocals, noPropertyAccessFromIndexSignature，并且启用了所有严格标志
ESLint 使用eslint strict+风格预设
esbuild bundler --单文件780KB捆绑包，树摇动，可选择缩小
Docker支持 --使用IB网关进行多阶段构建+组合

建筑

┌─────────────┐    stdio     ┌──────────────────────────────────────────────┐
│  MCP Client │◄────────────►│  ibkr-mcp                                    │
│  (AI Agent) │              │                                              │
└─────────────┘              │  app.ts ─► tools/ ─► services/ ─► ib_conn   │
                             │              │          │                     │
                             │          schemas/   middleware/               │
                             │        (zod validation) (guardrails,         │
                             │                          rate limit,         │
                             │                          error mapping)      │
                             └──────────────────────────────────────────────┘
                                                          │
                                                     TCP 4001/4002
                                                          │
                                                ┌─────────▼─────────┐
                                                │  TWS / IB Gateway │
                                                └───────────────────┘

先决条件

在设置IBKR MCP服务器之前，请确保您拥有以下内容：

必需

Node.js ≥ 20 — 下载
盈透证券账户 --资金或纸质交易账户
TWS（交易员工作站） 或 IB网关 — 下载
- 必须启用API连接：TWS→ Edit → 全局配置→ API → 设置
- 启用 “启用ActiveX和Socket客户端”
- 注意 插座端口 （默认值： 7497 对于TWS纸， 4002 Gateway论文）
- 可选择添加 127.0.0.1 到 受信任的IP 跳过连接提示

可选的

Docker&Docker编写 --用于集装箱化部署
克劳德桌面版, 光标，或任何兼容MCP的客户端——连接到服务器

IB网关与TWS

	IB网关	TWS
最适合	无头/服务器使用	交互式交易+API
纸张端口	`4002`	`7497`
实时端口	`4001`	`7496`
图形用户界面	最小	完整交易UI
稳定性	建议始终开启	可能需要互动

快速开始

安装和构建

git clone https://github.com/guramrit-dhillon/ibkr-mcp.git
cd ibkr-mcp
npm install
cp .env.example .env  # edit with your settings
npm run build

设置

1.配置IB网关/TWS

发射 IB网关 或 真无线立体声 并登录（使用纸质交易开始）
启用API：
- 真无线立体声：编辑→ 全局配置→ API → 设置
- IB网关：配置→ 设置→ API → 设置
检查 “启用ActiveX和Socket客户端”
注意 插座端口 （默认值 4002 对于Gateway论文， 7497 TWS纸张）
可选择添加 127.0.0.1 到 受信任的IP 避免连接确认对话框

2.配置MCP服务器

复制示例环境文件并对其进行编辑：

cp .env.example .env

中的关键设置 .env:

# Connection — match your IB Gateway/TWS settings
IB_HOST=127.0.0.1
IB_PORT=4002          # 4002=Gateway paper, 7497=TWS paper, 4001=Gateway live, 7496=TWS live
IB_CLIENT_ID=1
IB_MODE=paper         # paper | live

# Safety — start with read-only mode
IB_READ_ONLY=true     # blocks all order mutations; set to false when ready to trade

# Risk guardrails
RISK_MAX_ORDER_QTY=1000           # max shares/contracts per order
RISK_MAX_ORDER_NOTIONAL=100000    # max order value in USD
RISK_DAILY_LOSS_LIMIT=10000       # daily loss circuit breaker in USD

3.从MCP客户端连接

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ibkr": {
      "command": "npx",
      "args": ["ibkr-mcp"],
      "env": {
        "IB_HOST": "127.0.0.1",
        "IB_PORT": "4002",
        "IB_READ_ONLY": "true"
      }
    }
  }
}

光标

添加 .cursor/mcp.json 在您的项目或全局配置中：

{
  "mcpServers": {
    "ibkr": {
      "command": "npx",
      "args": ["ibkr-mcp"]
    }
  }
}

任何兼容stdio的MCP客户端

# The server communicates over stdin/stdout using the MCP protocol
npx ibkr-mcp

4.验证连接

连接后，尝试以下提示以确认一切正常：

“连接状态如何？” --应该显示 connected: true
“列出我的帐户” --应显示您的纸质/真实账户
“AAPL目前的价格是多少？” --应返回市场数据快照

示例提示

连接后，您可以向AI助手提出以下问题：

市场数据与研究

“AAPL目前的价格是多少？”
“显示过去6个月TSLA的历史每日柱状图”
“为我获取SPY、QQQ和IWM的报价快照”
“微软的基本面是什么——市盈率、市值、收益？”
“显示AMZN的订单深度”

合同和期权

“搜索所有与‘META’匹配的合同”
“AAPL有哪些可用的期权到期和罢工？”
“为下个月到期的SPY建立一个期权链，罢工接近资金”
“ES期货的交易规则是什么——分时大小、交易时间、订单类型？”

投资组合和账户

“我的账户摘要是什么——净清算、购买力、保证金？”
“显示我当前的所有职位”
“我今天的投资组合PnL是什么？”
“我的现金余额按货币计是多少？”
“显示100股GOOG的保证金要求”

订单与交易

“下达限价订单，以180美元的价格购买50股AAPL股票”
“预览购买200股微软股票的利润率影响”
“显示我所有的未结订单”
“下支架订单：在市场上买入100 TSLA，止盈300美元，止损250美元”
“我最近被处决了什么？”

风险与分析

“计算3月份到期的AAPL 200看涨期权的隐含波动率”
“我的投资组合中的希腊人是什么？”
“进行压力测试：如果SPY下降10%会发生什么？”
“按行业显示我的风险敞口明细”
“在95%的置信度下，我的投资组合风险价值是多少？”
“模拟在我的投资组合中增加500股NVDA的影响”

扫描仪和新闻

“扫描一下今天美国股市涨幅最大的股票”
“按音量显示最活跃的选项”
“为我获取TSLA的最新新闻头条”

管理员

“与IB网关的连接状态如何？”
“显示最近的错误日志”
“列出所有活动的流媒体订阅”

工具参考

合同（8个工具）

工具	说明
`contract_search`	使用可选筛选器按符号/名称搜索合同
`contract_details`	获取完整的合同详细信息（按conId或符号）
`contract_qualify`	确认合同——完全解决和验证
`contract_rules`	获取交易规则（最小交易时间、订单类型、交易时间）
`security_definitions_option_parameters`	获取期权链参数（到期、罢工）
`option_chain`	用希腊语构建过滤选项链
`instrument_metadata`	获取仪器元数据（行业、类别、长名称）
`symbol_to_conid_mapping`	将符号解析为合格的conId

市场数据（15种工具）

工具	说明
`market_data_snapshot`	获取当前市场数据的快照（买入、卖出、最后等）
`market_data_bulk_snapshot`	多个合约的批量快照
`historical_data`	获取历史OHLCV酒吧
`historical_ticks`	获取历史分时数据
`fundamental_data`	获取基本数据（财务、比率等）
`market_depth_snapshot`	获取当前订单簿深度快照
`market_data_stream_subscribe`	订阅流媒体市场数据
`market_data_stream_unsubscribe`	取消订阅流媒体市场数据
`tick_by_tick_stream_subscribe`	订阅逐笔数据
`tick_by_tick_stream_unsubscribe`	取消订阅逐点数据
`market_depth_stream_subscribe`	订阅流媒体订单簿
`market_depth_stream_unsubscribe`	取消订阅流媒体订单簿
`realtime_bars_stream_subscribe`	订阅实时5秒条形图
`realtime_bars_stream_unsubscribe`	取消订阅实时栏
`list_market_data_subscriptions`	列出所有活跃的市场数据订阅

订单（14个工具）

工具	说明
`order_place`	下新订单（LMT、MKT、STP、TRAIL等）
`order_modify`	修改现有订单
`order_cancel`	取消特定订单
`orders_cancel_all`	取消所有未结订单
`orders_open_list`	列出所有未结订单
`orders_completed_list`	列出已完成的订单
`executions_list`	列出最近执行的死刑
`order_preview`	预览订单影响（利润、佣金）
`exercise_options`	练习或失效选项
`bracket_order`	下括号订单（入市+止盈+止损）
`oco_order`	放置一个取消另一个订单组
`order_status_stream_subscribe`	订阅订单状态更新
`order_status_stream_unsubscribe`	取消订阅订单状态更新

账户（17个工具）

工具	说明
`accounts_list`	列出所有托管帐户
`account_summary`	获取账户摘要（NLV、购买力等）
`account_values`	获取所有帐户值（键值对）
`positions_list`	列出所有职位
`portfolio_list`	使用PnL列出投资组合
`pnl_account`	获取帐户级别PnL
`pnl_position`	获取位置级别PnL
`account_updates_subscribe`	订阅实时帐户更新
`account_updates_unsubscribe`	取消订阅帐户更新
`buying_power`	获得可用购买力
`cash_balances`	按货币获取现金余额
`leverage_metrics`	获取杠杆/利润指标
`margin_requirements`	获取合同的保证金要求
`fa_groups_list`	列出财务顾问组
`fa_profiles_list`	列出财务顾问简介
`fa_aliases_list`	列出财务顾问别名
`fa_replace`	替换财务顾问配置

风险分析（14种工具）

工具	说明
`option_price_calculate`	计算理论期权价格
`implied_volatility_calculate`	计算隐含波动率
`greeks_calculate`	计算期权价格
`portfolio_greeks`	获取总投资组合希腊
`stress_test_portfolio`	使用自定义场景运行投资组合压力测试
`exposure_by_symbol`	按符号获取名义敞口
`exposure_by_sector`	按行业获取风险细分
`value_at_risk`	计算投资组合的风险价值
`beta_exposure`	计算投资组合贝塔风险敞口
`correlation_matrix`	为投资组合生成相关矩阵
`simulate_trade_impact`	模拟假设交易的影响
`dividends_and_splits_history`	获取股息/分割历史记录
`corporate_actions_calendar`	获取即将采取的公司行动

新闻（6工具）

工具	说明
`news_providers_list`	列出可用的新闻提供商
`news_bulletins_subscribe`	订阅IB公告
`news_bulletins_unsubscribe`	取消订阅IB公告
`news_headlines`	获取合同的新闻头条
`news_article`	按ID获取完整新闻文章
`historical_news`	获取合同的历史新闻

扫描仪（5个工具）

工具	说明
`scanner_parameters`	获取可用的扫描仪参数XML
`scanner_run`	使用自定义条件运行市场扫描程序
`scanner_cancel`	取消正在运行的扫描仪订阅
`scanner_presets_list`	列出扫描仪预设
`scanner_run_preset`	使用预设名称运行扫描仪

管理员（7个工具）

工具	说明
`connection_status`	获取连接状态、正常运行时间、错误日志
`connection_reconnect`	强制重新连接到TWS/IB网关
`server_config`	查看当前服务器配置
`error_log`	获取最近的IB错误日志
`subscriptions_list`	列出所有活动订阅
`server_time`	获取服务器时间
`ping`	健康检查/ping

配置

通过环境变量进行所有配置（请参见 .env.示例):

变量	默认值	描述
`IB_HOST`	`127.0.0.1`	TWS/网关主机
`IB_PORT`	`4002` （纸）/ `4001` （实时）	API端口
`IB_CLIENT_ID`	`1`	客户端ID
`IB_MODE`	`paper`	`paper` 或 `live`
`IB_READ_ONLY`	`true`	阻止所有顺序突变
`IB_ACCOUNT_ID`	（自动）	帐户ID覆盖
`RISK_MAX_ORDER_QTY`	`1000`	每份订单的最大股份/合约数
`RISK_MAX_ORDER_NOTIONAL`	`100000`	最大名义订单（$）
`RISK_DAILY_LOSS_LIMIT`	`10000`	每日损失限额（$）
`RISK_ALLOWED_ORDER_TYPES`	`MKT,LMT,STP,STP_LMT,TRAIL`	允许的订单类型
`RISK_SYMBOL_ALLOWLIST`	（无）	只允许这些符号
`RISK_SYMBOL_DENYLIST`	（无）	屏蔽这些符号
`RISK_ALLOW_OUTSIDE_RTH`	`false`	允许在非工作时间下单
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`

码头工人

使用Docker Compose（推荐）

# Set credentials
cp .env.example .env
# Edit .env: TWS_USERID, TWS_PASSWORD, TRADING_MODE

# Start IB Gateway + MCP server
docker compose up -d

# Check logs
docker compose logs -f mcp

独立

docker build -t ibkr-mcp .
docker run --rm -i \
  -e IB_HOST=host.docker.internal \
  -e IB_PORT=4002 \
  ibkr-mcp

发展

# Run in development mode
npm run dev

# Type-check only
npm run typecheck

# Lint
npm run lint
npm run lint:fix

# Full check (typecheck + lint)
npm run check

# Run tests
npm test
npm run test:watch
npm run test:coverage

# Build (typecheck + bundle)
npm run build

# Bundle only (skip typecheck)
npm run build:bundle
npm run build:bundle:min  # minified

项目结构

src/
├── app.ts                    # MCP server bootstrap
├── config.ts                 # Environment-driven configuration
├── connection/
│   ├── ib_connection.ts      # IB API connection manager
│   └── event_bus.ts          # Typed event pub/sub
├── middleware/
│   ├── logging.ts            # JSON structured logger
│   ├── error_mapping.ts      # Error normalization + response envelope
│   ├── rate_limit.ts         # Token-bucket rate limiter
│   └── guardrails.ts         # Pre-trade safety checks
├── schemas/
│   ├── common.ts             # Shared types (contract, error, response)
│   ├── contract_schemas.ts   # Contract tool schemas
│   ├── market_data_schemas.ts
│   ├── order_schemas.ts
│   ├── account_schemas.ts
│   ├── news_schemas.ts
│   └── scanner_schemas.ts
├── services/
│   ├── contract_service.ts   # Contract operations
│   ├── market_data_service.ts
│   ├── orders_service.ts
│   ├── account_service.ts
│   ├── risk_service.ts
│   ├── news_service.ts
│   └── scanner_service.ts
├── tools/
│   ├── index.ts              # Tool aggregation + O(1) dispatch
│   ├── contract_tools.ts     # Tool definitions + handlers
│   ├── market_data_tools.ts
│   ├── order_tools.ts
│   ├── account_tools.ts
│   ├── risk_tools.ts
│   ├── news_tools.ts
│   ├── scanner_tools.ts
│   └── admin_tools.ts
└── resources/
    ├── index.ts              # MCP resource definitions
    └── server_instructions.md
tests/
├── config.test.ts
├── error_mapping.test.ts
├── guardrails.test.ts
├── rate_limit.test.ts
├── schemas.test.ts
└── event_bus.test.ts

响应格式

每个工具都返回一个标准化的信封：

{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2025-01-15T12:34:56.789Z",
    "latency_ms": 42
  }
}

出现错误时：

{
  "success": false,
  "data": null,
  "error": {
    "code": "IB_CONTRACT_NOT_FOUND",
    "message": "No matching contract found",
    "details": {},
    "ib_error_code": 200,
    "retriable": false
  },
  "meta": { ... }
}

安全

默认情况下为只读 — IB_READ_ONLY=true 阻断所有顺序突变
交易前护栏 --数量限额、名义限额、每日损失限额
符号过滤 --反歧视/反歧视执法
订单类型限制 --只允许配置订单类型
外部RTH保护 --默认情况下禁用

免责声明

本项目与Interactive Brokers Group，股份有限公司无关、不受其认可或赞助。“Interactive Broker”、“IBKR”、“TWS”和“IB Gateway”是Interactive Broers Group，股份有限公司的注册商标 API许可协议。此软件按原样提供，不提供任何保修，使用风险由您自行承担，尤其是在下实时订单时。

许可证

麻省理工学院