关键词

盈透证券交易数据市场分析股票期权财务信息

项目简介

IBTraderMCP 是一个基于 FastMCP 框架开发的盈透证券 (Interactive Brokers) 交易数据服务器。它允许大型语言模型 (LLM) 通过标准化的 Model Context Protocol (MCP) 协议，安全地访问您的盈透证券账户信息、查询实时/历史市场数据、获取公司基本面数据以及交易日历等。此服务器作为LLM应用与IB交易平台之间的高效桥梁，提供可扩展的数据服务，赋能智能体进行更高级的金融分析和决策支持。

主要功能点

  • 账户与仓位查询:
    • 获取账户摘要，包括净清算价值、现金余额、可用资金、购买力及保证金信息。
    • 查询所有股票和期权持仓的详细信息，包含代码、数量、市值、平均成本、未实现盈亏和已实现盈亏。
    • 提供全面的仓位汇总分析，如总市值、总盈亏和持仓分布比例。
  • 市场数据获取:
    • 获取股票的历史K线数据，支持灵活的时间范围和多种K线周期（如1分钟、5分钟、30分钟、1小时、日K、周K、月K）。
    • 内置智能缓存机制（使用SQLite本地缓存），显著提升重复查询的市场数据获取速度。
  • 交易日历工具:
    • 查询指定日期范围内的交易日及其每日开盘、收盘时间。
    • 支持多个主要交易所（如NYSE、NASDAQ）。
  • 基本面数据查询:
    • 获取公司基本信息，如公司名称、行业、板块、交易所等（无需IB订阅）。
    • 获取公司概览、财务摘要和分析师报告（后三项需购买IB基本面数据订阅）。
  • 日志记录与缓存:
    • 结构化日志记录系统，便于操作审计和错误追踪。
    • 将市场数据和操作日志持久化存储在本地SQLite数据库中。

安装步骤

在运行 IBTraderMCP 服务器之前，请确保满足所有环境要求并完成配置。

  1. 环境要求:

    • Python 3.8 或更高版本
    • 已安装并运行 Interactive Brokers Gateway 或 TWS (Trader Workstation) 应用程序。
    • 一个有效的盈透证券账户（可以是模拟盘或实盘）。

  2. 克隆仓库: 打开您的终端或命令行工具，执行以下命令克隆项目仓库：

    git clone https://github.com/WisdomShun/IBTraderMCP.git
cd IBTraderMCP

  3. 安装依赖: 进入项目目录后，安装所有Python依赖：

    pip install -e .

  4. 配置环境变量: 复制配置文件模板 '.env.example' 到 '.env' 文件：

    cp .env.example .env

    编辑 '.env' 文件，根据您的盈透证券账户和API连接信息进行修改：

    # Interactive Brokers Gateway 连接配置
IB_HOST=127.0.0.1           # IB Gateway 所在主机IP地址
IB_PORT=7497                # IB Gateway API 端口。模拟盘通常是 7497，实盘是 7496。
IB_CLIENT_ID=1              # 客户端ID，确保您运行的每个API客户端使用唯一的ID。
IB_ACCOUNT=DU123456         # 替换为您的盈透证券账户号 (例如：U123456)。

# MCP 服务器监听配置 (供MCP客户端连接)
MCP_ADDRESS=127.0.0.1       # MCP 服务器监听的IP地址
MCP_PORT=4211               # MCP 服务器监听的端口
MCP_PATH=/ibkr              # MCP 服务器的API路径

# 缓存和日志配置 (可根据您的需求进行调整)
CACHE_DB_PATH=./data/trading.db  # SQLite 数据库文件路径
LOG_LEVEL=INFO                   # 日志级别 (DEBUG, INFO, WARNING, ERROR, CRITICAL)
LOG_PATH=./logs/                 # 日志文件存储目录

    重要安全提示: 盈透证券的账户密码通常需要通过环境变量来安全配置，而不是直接写入 '.env' 文件。请根据您的IB Gateway或TWS配置，将您的IB（模拟/实盘）账号密码信息配置到操作系统环境变量中，例如：

    • 'TWS_PASSWORD' (用于实盘账号密码)
    • 'TWS_PASSWORD_PAPER' (用于模拟账号密码)
    • 'TWS_USERID' (用于实盘账号用户名)
    • 'TWS_USERID_PAPER' (用于模拟账号用户名)

  5. 启动 IB Gateway 或 TWS: 在启动 IBTraderMCP 服务器之前，请务必启动您的 IB Gateway 或 TWS。同时，确保在 IB 应用程序的“配置”->“API”->“Settings”中已启用 API 连接，并核对端口设置与您 '.env' 文件中的 'IB_PORT' 一致。

服务器启动与MCP客户端配置

  1. 运行 IBTraderMCP 服务器: 在项目根目录运行以下命令来启动 MCP 服务器：

    python -m src.server

    或者使用 FastMCP 命令行工具：

    fastmcp run src/server.py --host 127.0.0.1 --port 4211 --path /ibkr

    服务器启动后，它将监听 'MCP_ADDRESS' 和 'MCP_PORT'（默认 '127.0.0.1:4211'），并提供 '/ibkr' 路径下的服务。

  2. MCP 客户端的连接配置示例: 您的 MCP 客户端（例如，一个集成LLM的智能体框架）需要一个JSON格式的配置文件来连接 IBTraderMCP 服务器并了解其提供的工具。以下是一个配置示例，展示了客户端如何连接服务器以及服务器公开的工具及其参数：

    {
  "name": "IBTraderMCP",
  "command": ["python", "-m", "src.server"],
  "args": [
    "--transport", "streamable-http",
    "--host", "127.0.0.1",
    "--port", "4211",
    "--path", "/ibkr",
    "--log-level", "debug"
  ],
  "description": "连接盈透证券 (Interactive Brokers) 交易平台，提供账户、仓位、市场数据和基本面分析的上下文信息及功能。",
  "tools": [
    {
      "name": "get_account_summary",
      "description": "获取账户摘要，包括净清算价值、现金余额、可用资金、购买力及保证金信息。",
      "parameters": {
        "type": "object",
        "properties": {
          "currency": { "type": "string", "description": "筛选的币种 (默认: USD)", "default": "USD" }
        }
      }
    },
    {
      "name": "get_stock_positions",
      "description": "检索所有当前股票仓位，包含代码、数量、市值、平均成本和未实现盈亏等详细信息。",
      "parameters": { "type": "object", "properties": {} }
    },
    {
      "name": "get_option_positions",
      "description": "检索所有当前期权仓位，包含合约规格（行权价、到期日、看涨/看跌）、数量、市值和未实现盈亏等详细信息。",
      "parameters": { "type": "object", "properties": {} }
    },
    {
      "name": "get_position_summary",
      "description": "获取全面的仓位汇总，包括总市值、总盈亏、仓位分配百分比以及股票与期权的细分。",
      "parameters": { "type": "object", "properties": {} }
    },
    {
      "name": "get_historical_kline",
      "description": "获取历史K线（OHLCV）数据，支持灵活的时间范围。支持多种K线周期（1分钟至1个月），并利用缓存机制提高性能。",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "description": "股票代码 (例如: 'AAPL', 'TSLA')" },
          "bar_size": { "type": "string", "description": "K线周期 - '1D' (日K), '1W' (周K), '1M' (月K), '1H' (小时K), '30min', '15min', '5min', '1min'", "default": "1D" },
          "duration": { "type": "string", "description": "时间范围 - 例如: '1 Y' (1年), '6 M' (6个月), '1 W' (1周), '1 D' (1天)", "default": "1 Y" },
          "end_datetime": { "type": "string", "description": "K线数据的结束日期/时间 (ISO格式，默认当前时间)"},
          "use_cache": { "type": "boolean", "description": "是否使用缓存数据以加快检索速度 (默认: true)", "default": true },
          "force_refresh": { "type": "boolean", "description": "是否强制刷新，忽略缓存直接从IB获取数据 (默认: false)", "default": false }
        },
        "required": ["symbol"]
      }
    },
    {
      "name": "get_daily_kline",
      "description": "获取指定天数的日K线数据。方便的日OHLCV数据检索封装。",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "description": "股票代码" },
          "days": { "type": "integer", "description": "要检索的交易日天数 (默认: 365)", "default": 365 }
        },
        "required": ["symbol"]
      }
    },
    {
      "name": "get_weekly_kline",
      "description": "获取指定周数的周K线数据。适用于中期趋势分析。",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "description": "股票代码" },
          "weeks": { "type": "integer", "description": "要检索的周数 (默认: 52)", "default": 52 }
        },
        "required": ["symbol"]
      }
    },
    {
      "name": "get_monthly_kline",
      "description": "获取指定月数的月K线数据。理想的长期趋势分析和历史业绩回顾。",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "description": "股票代码" },
          "months": { "type": "integer", "description": "要检索的月数 (默认: 12)", "default": 12 }
        },
        "required": ["symbol"]
      }
    },
    {
      "name": "get_trading_calendar",
      "description": "获取指定日期范围内带有市场开盘/收盘时间的交易日历。返回排除周末和节假日的交易日列表。",
      "parameters": {
        "type": "object",
        "properties": {
          "start_date": { "type": "string", "description": "开始日期，格式为 YYYY-MM-DD" },
          "end_date": { "type": "string", "description": "结束日期，格式为 YYYY-MM-DD" },
          "exchange": { "type": "string", "description": "交易所代码 (默认: 'NYSE')", "default": "NYSE" }
        },
        "required": ["start_date", "end_date"]
      }
    },
    {
      "name": "get_company_info",
      "description": "获取公司基本信息，包括公司名称、行业分类、板块、主要交易所和货币。无需IB订阅。",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "description": "股票代码" }
        },
        "required": ["symbol"]
      }
    },
    {
      "name": "get_company_overview",
      "description": "获取全面的公司概况，包括业务描述、运营摘要和公司结构。需要IB基本面数据订阅。",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "description": "股票代码" }
        },
        "required": ["symbol"]
      }
    },
    {
      "name": "get_financial_summary",
      "description": "获取财务摘要，包括营收、利润、利润率、市盈率、每股收益 (EPS) 和其他基本面指标。需要IB基本面数据订阅。",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "description": "股票代码" }
        },
        "required": ["symbol"]
      }
    },
    {
      "name": "get_analyst_reports",
      "description": "获取分析师推荐、共识评级、目标价和华尔街分析师的近期评级变化。需要IB基本面数据订阅。",
      "parameters": {
        "type": "object",
        "properties": {
          "symbol": { "type": "string", "description": "股票代码" }
        },
        "required": ["symbol"]
      }
    }
  ]
}

  3. 基本使用方法: 启动 IBTraderMCP 服务器后，您的 MCP 客户端（例如，一个集成 LLM 的智能体）就可以通过配置的地址和端口连接到该服务器。LLM 智能体可以像调用普通函数一样，通过 JSON-RPC 请求服务器上公开的各种“工具”（例如 'get_account_summary' 或 'get_daily_kline'），并传递相应的参数。服务器会执行这些操作，通过 'ib_insync' 库与盈透证券 API 交互，然后返回结构化的数据，供 LLM 进行分析、报告生成或作为进一步决策的上下文信息。例如，LLM 可以请求“查询苹果公司 (AAPL) 最近30天的日K线数据”，服务器将执行 'get_daily_kline(symbol="AAPL", days=30)' 并返回结果。

信息

分类

商业系统

访问项目