内部MCP服务器

Name: 内部MCP服务器
Author: Hellek1

作者：Hellek14 星标更新：2025-10-30

安装使用来源：spider==github.com

项目介绍

IB 异步 MCP 服务器

轻量级模型上下文协议（MCP）服务器通过异步的ib_async库和FastMCP暴露只读的交互式经纪人数据（合约、历史数据、基本面数据、新闻、投资组合、账户）。非常适合将金融数据输入到LLM工作流程和自主代理中，同时保持交易禁用。

概述

此目录包含一个MCP（模型上下文协议）服务器，该服务器封装了ib_async库，允许LLMs与交互式经纪人数据进行交互。

功能

MCP服务器提供了以下工具供LLM交互使用：

1. 合约查询和转换

lookup_contract: 根据股票代码和可选的交易所/货币查询合约详情
ticker_to_conid: 将股票代码转换为合约ID（conid）

2. 市场数据

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

3. 新闻

get_news: 获取合约的当前新闻文章
get_historical_news: 在日期范围内获取历史新闻文章

4. 基本面数据

get_fundamental_data: 获取包括财务概要、所有权、财务报表等在内的基本面数据

5. 投资组合和账户信息

get_portfolio: 获取投资组合仓位和详情
get_account_summary: 获取账户概要信息
get_positions: 获取当前仓位

预备条件

交互式经纪人账户：您需要一个有效的IB账户
IB网关或TWS：下载并安装以下任一选项：
- IB网关（稳定版） - 推荐用于仅API使用
- IB网关（最新版） - 最新功能
- 交易员工作站（TWS） - 完整交易平台
API配置：
- 在TWS/Gateway中启用API访问：配置 → API → 设置 并勾选“启用ActiveX和Socket客户端”
- 设置适当的端口（默认：TWS为7497，Gateway为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客户端集成。

# 使用默认设置（TWS在localhost:7497）
poetry run ib-mcp-server

# 自定义IB网关连接
poetry run ib-mcp-server --host 127.0.0.1 --port 4001 --client-id 1

# 显示所有选项的帮助
poetry run ib-mcp-server --help

HTTP模式

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

# 本地HTTP服务器
poetry run ib-mcp-server --transport http --http-host 127.0.0.1 --http-port 8000

# 监听所有接口（用于Docker/远程访问）
poetry run ib-mcp-server --transport http --http-host  0.0.0.0 --http-port 8000

# 使用环境变量
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，Gateway为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 vs HTTP

使用场景	STDIO	HTTP
Claude Desktop集成	✅ 推荐	❌ 不支持
本地单客户端使用	✅ 简单设置	⚠️ 过度复杂
多客户端访问	❌ 不可能	✅ 支持
远程/网络访问	❌ 不可能	✅ 支持
Docker部署	✅ 简单	✅ 更灵活
生产使用	✅ 默认安全	⚠️ 需要认证/代理

Docker

构建

docker build -t ib-mcp .

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

STDIO模式（默认）

在macOS/Windows Docker Desktop上，可以通过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/Gateway端口是可访问的：

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服务器运行以支持多客户端或远程访问：

# 本地访问
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

# 或使用命令行参数
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模式

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

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

{
   "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"
         ]
      }
   }
}

注意：

在macOS/Windows Docker Desktop上删除--add-host行（仅在Linux上需要）。

HTTP模式

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

可用工具

合约查询

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_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="")

示例用法

一旦通过MCP连接到LLM，您可以询问如下问题：

"查询AAPL的合约详情"
"获取TSLA过去一个月的每日历史数据"
"微软有哪些最近的新闻文章？"
"显示Google的财务概要"
"我目前的投资组合中有哪些仓位？"

数据格式

XML到Markdown转换

服务器会自动将XML格式的基本面数据转换为Markdown，以便在LLM交互中更易读。

错误处理

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

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

故障排除

连接问题

"无法连接到交互式经纪人"
- 确保TWS/Gateway正在运行
- 检查是否在设置中启用了API
- 验证端口号匹配（TWS为7497，Gateway为4001）
- 检查防火墙设置
"未找到合约"
- 验证符号拼写
- 尝试不同的交易所（NYSE, NASDAQ vs SMART）
- 检查证券类型是否正确
"没有市场数据"
- 确保您有适当的市场数据订阅
- 检查市场是否开放以获取实时数据
- 如果没有实时数据，尝试延迟数据模式

性能提示

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

安全考虑

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

贡献

分支：feat/xyz
安装开发依赖：poetry install
激活预提交：pre-commit install
运行测试：poetry run pytest -q
提交PR并附带简洁描述。

发布（维护者）

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

支持与参考资料

IB API功能：ib_async文档
MCP协议：MCP规范
交互式经纪人：IB API文档

根据BSD 3-Clause许可发布。欢迎贡献。