使用说明

项目简介

'ib-mcp' 是一个基于 Model Context Protocol (MCP) 的轻量级服务器，它通过 'ib_async' 库连接到盈透证券（Interactive Brokers, IB）账户，并以只读方式向大型语言模型（LLM）客户端提供金融市场数据。LLM可以通过预定义的工具查询股票合约、历史数据、新闻、公司基本面、投资组合和账户摘要等信息，从而赋能智能金融应用。

主要功能点

合约查找与转换: 根据股票代码查找合约详情，或将股票代码转换为合约ID。
市场数据获取: 检索指定股票的历史市场数据，支持自定义时长、K线周期和数据类型。
新闻查询: 获取股票的最新新闻文章和指定日期范围内的历史新闻。
基本面数据: 检索公司的财务摘要、所有权信息、财务报表等基本面数据。
投资组合与账户信息: 查看投资组合持仓和账户摘要信息。
数据格式化: 自动将XML格式的基本面数据转换为易读的Markdown格式，便于LLM理解。
多传输协议支持: 支持通过标准输入/输出（STDIO）和HTTP协议进行通信。

安装步骤

准备盈透证券环境:
- 拥有一个活跃的盈透证券账户。
- 下载并安装 IB Gateway (推荐用于API) 或 Trader Workstation (TWS)。
- 在 TWS/Gateway 中启用 API 访问：'配置 → API → 设置'，勾选 "Enable ActiveX and Socket Clients"。
- 设置合适的端口（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 客户端，例如 Claude Desktop)

MCP客户端（如Claude Desktop）需要通过JSON配置来启动和连接到此服务器。以下是一个示例配置，您需要根据实际情况调整：

{
   "mcpServers": {
      "ib-mcp": {
         "command": "docker",
         "args": [
            "run",
            "--rm",
            // 在 Linux Docker 环境下，如果TWS/Gateway运行在宿主机，可能需要添加此行：
            // "--add-host","host.docker.internal:host-gateway",
            "-e","IB_HOST=host.docker.internal", // 盈透证券TWS/Gateway所在的主机地址
            "-e","IB_PORT=7497",               // 盈透证券TWS/Gateway的监听端口 (TWS:7497, Gateway:4001)
            "-e","IB_CLIENT_ID=1",             // 为本次连接分配一个唯一的客户端ID
            "ghcr.io/hellek1/ib-mcp:latest"    // 使用预构建的 Docker 镜像的名称和标签
         ]
         // 如果您希望直接在本地运行服务器（非Docker），且MCP客户端支持通过路径启动，
         // 则"command"和"args"可能会类似如下配置：
         // "command": "/usr/bin/env", // 通常用于启动Poetry环境中的脚本
         // "args": [
         //    "poetry", "run", "ib-mcp-server",
         //    "--host", "127.0.0.1",
         //    "--port", "7497",
         //    "--client-id", "1",
         //    // 如果客户端通过HTTP连接，还需要指定：
         //    // "--transport", "http",
         //    // "--http-host", "127.0.0.1",
         //    // "--http-port", "8000"
         // ]
      }
   }
}

配置说明:

'"ib-mcp"': 您为该MCP服务器定义的名称，可自定义。
'"command"': 启动服务器的可执行文件或脚本的路径。上述示例使用'docker'命令运行预构建的Docker镜像。
'"args"': 传递给'command'的参数列表。
- '-e IB_HOST=host.docker.internal': 设置盈透证券TWS/Gateway所在的主机地址。'host.docker.internal'通常用于Docker容器访问宿主机。
- '-e IB_PORT=7497': 设置TWS/Gateway的监听端口。根据您的配置，TWS默认是7497，IB Gateway默认是4001。
- '-e IB_CLIENT_ID=1': 为本次API连接分配一个唯一的客户端ID。
- 'ghcr.io/hellek1/ib-mcp:latest': 指定要运行的Docker镜像的名称和标签。您也可以在本地构建后使用自定义镜像名称。
本地运行而非Docker: 如果不在Docker中运行，'command'可以指向您的'poetry'环境中的启动命令。具体路径可能需要根据您的系统和'poetry'安装情况进行调整。
HTTP模式: 如果MCP客户端支持HTTP连接，您可以将'command'和'args'配置为启动HTTP模式的服务器，然后客户端直接配置连接到服务器的HTTP地址（例如'http://localhost:8000/mcp/'）。

基本使用方法

启动 IB Gateway/TWS 并确保 API 连接已启用。

在本地启动 MCP 服务器（STDIO 模式）:

cd ib-mcp
poetry run ib-mcp-server --host 127.0.0.1 --port 7497 --client-id 1

（这将启动服务器，并在标准输入/输出上等待 MCP 客户端的连接。）

在本地启动 MCP 服务器（HTTP 模式）：

cd ib-mcp
poetry run ib-mcp-server --transport http --http-host 127.0.0.1 --http-port 8000

（服务器将在 'http://127.0.0.1:8000/mcp/' 监听连接，允许多个客户端通过网络访问。）

将 MCP 客户端（如 Claude Desktop）连接到服务器。 客户端连接成功后，LLM 即可通过以下示例指令与服务器交互：
- "查找苹果公司 (AAPL) 的合约详情。"
- "获取特斯拉 (TSLA) 最近一个月的每日历史数据。"
- "微软 (MSFT) 有哪些最新新闻？"
- "显示谷歌 (GOOGL) 的财务摘要。"
- "我的投资组合中目前有哪些持仓？"

关键词