使用说明

IB异步MCP服务器

轻量级模型上下文协议（MCP）服务器通过异步方式公开Interactive Brokers的只读数据（合约、历史数据、基本面、新闻、投资组合、账户） ib_async 图书馆和 FastMCP非常适合将财务数据输入LLM工作流程和自主代理，同时保持交易禁用。

概述

此目录包含一个MCP（模型上下文协议）服务器，该服务器包装ib_async库，以允许LLM与盈透证券数据交互。

特性

MCP服务器为LLM交互提供以下工具：

1.合同查询和转换

lookup_合同：按股票代码和可选交易所/货币查找合同详细信息
ticker_to_conid：将股票代码转换为合约ID（conid）

2.市场数据

获取历史数据：检索具有可配置持续时间、条形图大小和数据类型的历史市场数据

3.选项

get_option_chain：列出基础选项的选项链参数（过期和罢工），具有罢工范围过滤和分页功能
获取选项报价：期权行权列表的批量买入/卖出/最后一次/收盘和模型IV/delta；默认为延迟冻结数据（不需要OPRA订阅）
get_index_quote：指数的现货报价（最后/收盘/买入/卖出），可用于现货计算

4.新闻

获取新闻：检索合同的当前新闻文章
获取历史新闻：检索日期范围内的历史新闻文章

5.基础数据

获取基本数据：检索基本数据，包括财务摘要、所有权、财务报表等

6.投资组合和账户信息

get_portfolio：检索投资组合头寸和详细信息
get_count_summary：检索帐户摘要信息
get_positions：使用合约元数据检索当前头寸，包括期权到期/罢工/权利/乘数字段

先决条件

盈透证券账户：您需要一个有效的IB帐户
IB网关或TWS：下载并安装：
- IB网关（稳定） -建议仅使用API
- IB网关（最新） -最新功能
- 交易员工作站（TWS） -全交易平台
API配置:
- 在TWS/网关中启用API访问： Configure → API → Settings 并选中“启用ActiveX和Socket客户端”
- 设置适当的端口（默认值：TWS为7497，网关为4001）
- 加 127.0.0.1 如果本地连接，则连接到受信任的IP

安装

来源（开发）

git clone https://github.com/Hellek1/ib-mcp.git
cd ib-mcp
pip install poetry
poetry install

用法

运行MCP服务器

STDIO模式（默认）

默认模式作为可生成的MCP服务器运行，通过标准输入/输出进行通信。这非常适合与Claude Desktop等MCP客户端集成。

# Using default settings (TWS on localhost:7497)
poetry run ib-mcp-server

# Custom IB Gateway connection
poetry run ib-mcp-server --host 127.0.0.1 --port 4001 --client-id 1

# Help with all options
poetry run ib-mcp-server --help

HTTP模式

HTTP模式运行一个在主机和端口上监听的持久服务器，实现多客户端访问和网络连接。

# Local HTTP server
poetry run ib-mcp-server --transport http --http-host 127.0.0.1 --http-port 8000

# Listen on all interfaces (for Docker/remote access)
poetry run ib-mcp-server --transport http --http-host 0.0.0.0 --http-port 8000

# Using environment variables
IB_MCP_TRANSPORT=http IB_MCP_HTTP_HOST=127.0.0.1 IB_MCP_HTTP_PORT=8000 poetry run ib-mcp-server

安全说明：默认情况下，HTTP模式绑定到localhost（127.0.0.1）。对于远程访问，请放置在具有适当身份验证的反向代理后面，并使用受保护的网络。

命令行选项

IB连接

--host：IB网关/TWS主机（默认值：127.0.0.1）
--port：IB网关/TWS端口（默认值：TWS为7497，网关为4001）
--client-id：连接的唯一客户端ID（默认值：1）

传输配置

--transport：传输协议- stdio （默认）或 http
--http-host：HTTP服务器主机（默认值：127.0.0.1）
--http-port：HTTP服务器端口（默认值：8000）

环境变量

您还可以使用环境变量而不是标志：

IB连接

IB_HOST
IB_PORT
IB_CLIENT_ID

运输

IB_MCP_TRANSPORT
IB_MCP_HTTP_HOST
IB_MCP_HTTP_PORT

如果同时提供标记和环境变量，则标记将覆盖它们。

何时使用STDIO与HTTP

用例	STDIO	HTTP
克劳德桌面集成	✅ 推荐	❌ 不支持
本地单客户端使用情况	✅ 简单设置	⚠️ 过度杀戮
多客户端访问	❌ 不可能	✅ 支持
远程/网络访问	❌ 不可能	✅ 支持
Docker部署	✅ 简单	✅ 更灵活
生产使用	✅ 默认安全	⚠️ 需要身份验证/代理

码头工人

构建

docker build -t ib-mcp .

运行（连接到主机上运行的TWS）

STDIO模式（默认）

在macOS/Windows Docker桌面上，您可以通过以下方式访问主机 host.docker.internal （已为默认值）：

docker run --rm -it \
   -e IB_HOST=host.docker.internal \
   -e IB_PORT=7497 \
   -e IB_CLIENT_ID=1 \
   ghcr.io/hellek1/ib-mcp

在Linux上，您可能需要添加 --add-host host.docker.internal:host-gateway 并确保TWS/网关端口可访问：

docker run --rm -it \
   --add-host host.docker.internal:host-gateway \
   -e IB_HOST=host.docker.internal \
   -e IB_PORT=7497 \
   ghcr.io/hellek1/ib-mcp

如果愿意，直接覆盖参数：

docker run --rm -it ghcr.io/hellek1/ib-mcp --host host.docker.internal --port 4001 --client-id 2

HTTP模式

作为HTTP服务器运行，用于多客户端或远程访问：

# Local access
docker run --rm -it -p 8000:8000 \
   -e IB_HOST=host.docker.internal \
   -e IB_PORT=7497 \
   -e IB_MCP_TRANSPORT=http \
   -e IB_MCP_HTTP_HOST=0.0.0.0 \
   -e IB_MCP_HTTP_PORT=8000 \
   ghcr.io/hellek1/ib-mcp

# Or using command line arguments
docker run --rm -it -p 8000:8000 \
   ghcr.io/hellek1/ib-mcp \
   --host host.docker.internal --port 7497 \
   --transport http --http-host 0.0.0.0 --http-port 8000

HTTP服务器将在 http://localhost:8000/mcp/.

MCP客户端集成

STDIO模式

服务器使用MCP协议通过stdio进行通信。它可以与MCP兼容的工具和LLM应用程序集成。

使用Docker的MCP客户端配置示例（例如Claude Desktop）：

{
   "mcpServers": {
      "ib-async": {
         "command": "docker",
         "args": [
            "run",
            "--rm",
            "--add-host","host.docker.internal:host-gateway",
            "-e","IB_HOST=host.docker.internal",
            "-e","IB_PORT=7497",
            "-e","IB_CLIENT_ID=1",
            "ghcr.io/hellek1/ib-mcp:latest"
         ]
      }
   }
}

笔记：

移除 --add-host macOS/Windows Docker桌面上的行（仅在Linux上需要）。

HTTP模式

对于HTTP模式，请连接到服务器 http://localhost:8000/mcp/ 使用任何兼容MCP的HTTP客户端。

可用工具

合同查询

lookup_contract(symbol, sec_type="STK", exchange="SMART", currency="USD")
ticker_to_conid(symbol, sec_type="STK", exchange="SMART", currency="USD")

市场数据

get_historical_data(symbol, duration="1 M", bar_size="1 day", data_type="TRADES", exchange="SMART", currency="USD")

选项

get_option_chain(symbol, sec_type="IND", exchange="CBOE", currency="USD", trading_class="", min_strike=0.0, max_strike=0.0, max_strikes=20, strike_offset=0)
get_option_quotes(symbol, expiry, right, strikes, exchange="SMART", currency="USD", trading_class="", use_delayed=True)
get_index_quote(symbol, exchange="CBOE", currency="USD", use_delayed=True)

get_option_chain 返回可用的到期时间加上过滤后的执行窗口到 [min_strike, max_strike] （0=无界）并用 max_strikes （默认值20）和 strike_offset；输出说明如何翻页到下一个窗口。当标的列出多个交易类别（如SPX和SPXW）时，通过 trading_class 第一页链。 get_option_quotes 最多可获取20个独特每次呼叫的罢工次数（忽略重复，以尊重IB起搏），默认为延迟冻结数据，因此无需OPRA订阅即可工作 use_delayed=false 实时数据。这两个工具都是只读的。

新闻

get_news(symbol, provider_codes="", exchange="SMART", currency="USD")
get_historical_news(symbol, start_date, end_date, provider_codes="", max_count=10, exchange="SMART", currency="USD")

基础

get_fundamental_data(symbol, report_type="ReportsFinSummary", exchange="SMART", currency="USD")

可用报告类型：

ReportsFinSummary：财务摘要
ReportsOwnership：所有权信息
ReportsFinStatements：财务报表
RESC：研究报告
CalendarReport：日历事件

投资组合和账户

get_portfolio(account="")
get_account_summary(account="")
get_positions(account="")

get_positions 返回一个包含帐户、符号、安全类型的markdown表，头寸、平均成本、货币、汇率、本地交易品种、交易类别，以及合约ID。期权头寸还包括到期、行权、右方和乘数。

示例用法

通过MCP连接到LLM后，您可以提出以下问题：

“查找AAPL的合同详细信息”
“获取TSLA上个月的每日历史数据”
“显示400到550之间的XSP选项链罢工”
获取XSP到期日20261218在440、450和460点的看跌报价
“微软最近的新闻报道是什么？”
“给我看谷歌的财务摘要”
“我目前在投资组合中有哪些头寸？”

数据格式

XML到Markdown的转换

服务器自动将XML格式的基础数据转换为markdown，以提高LLM交互的可读性。

错误处理

服务器包括全面的错误处理，并在以下情况下提供有意义的错误消息：

IB连接失败
请求的符号无效
市场数据不可用
出现身份验证问题

故障排除

连接问题

“无法连接到盈透证券”
- 确保TWS/网关正在运行
- 检查API是否已在设置中启用
- 验证端口号是否匹配（TWS为7497，网关为4001）
- 检查防火墙设置
“未找到合同”
- 验证符号拼写
- 尝试不同的交易所（纽约证券交易所、纳斯达克与SMART）
- 检查安全类型是否正确
“无市场数据”
- 确保您有适当的市场数据订阅
- 检查市场是否对实时数据开放
- 如果实时不可用，请尝试延迟数据模式

性能提示

尽可能使用特定的交换，而不是“SMART”路由
将历史数据请求限制在合理的时间范围内
为频繁访问的符号缓存合约ID

安全考虑

MCP服务器以只读模式运行-没有下单功能
凭证由IB网关/TWS应用程序处理
服务器仅访问您在IB帐户中有权查看的数据

贡献

分叉与分支： feat/xyz
安装dev-deps： poetry install
激活预提交： pre-commit install
运行测试： poetry run pytest -q
用简洁的描述打开PR。

发布（维护人员）

poetry version patch  # or minor / major
poetry build
poetry publish --username __token__ --password <pypi-token>
git tag v$(poetry version -s)
git push --tags

支持和参考

IB API功能： IB异步文档
MCP协议： MCP规范
互动经纪商： IB API文件

根据BSD 3条款许可证授权。欢迎捐款。

使用说明

IB异步MCP服务器

概述

特性

1.合同查询和转换

2.市场数据

3.选项

4.新闻

5.基础数据

6.投资组合和账户信息

先决条件

安装

来源（开发）

用法

运行MCP服务器

STDIO模式（默认）

HTTP模式

命令行选项

IB连接

传输配置

环境变量

IB连接

运输

何时使用STDIO与HTTP

码头工人

构建

运行（连接到主机上运行的TWS）

STDIO模式（默认）

HTTP模式

MCP客户端集成

STDIO模式

HTTP模式

可用工具

合同查询

市场数据

选项

新闻

基础

投资组合和账户

示例用法

数据格式

XML到Markdown的转换

错误处理

故障排除

连接问题

性能提示

安全考虑

贡献

发布（维护人员）

支持和参考

相关 MCP

AKShare One MCP 股市数据服务

金融数据MCP服务器

加密货币交易集成服务

Alpaca交易MCP服务器

金融数据服务

金融数据分析服务器