mcpField
W
Webull OpenAPI

Webull OpenAPI

本地服务
github.com/webull-inc金融数据303 天前更新

关于 Webull OpenAPI

Webull OpenAPI 是供 AI 助手访问 Webull 行情数据和交易功能的 MCP 服务,支持多个地区与资产类型,并提供可配置的订单限额、标的白名单和审计日志。

主要功能

  1. 01覆盖股票及其他资产的行情数据
  2. 02筛选器、自选列表和基本面数据
  3. 03提交和管理交易订单
  4. 04按地区处理账户与订单
  5. 05订单限额、标的白名单和审计日志

适用场景

  1. 01获取报价、K 线和市场快照
  2. 02查看筛选结果并管理自选列表
  3. 03查询公司资料和财务报表
  4. 04在配置的控制下提交或管理订单

MCP 相关

该服务将 Webull 行情数据、标的、账户和交易能力作为工具提供给 MCP 客户端。可通过 WEBULL_TOOLSETS 启用工具类别。

配置

本地服务的配置在各客户端中通用,复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
"mcpServers": {
"webull-inc-webull-openapi": {
"command": "uvx",
"args": [
"webull-openapi-mcp"
]
}
}
}
启动命令uvx webull-openapi-mcp

本地服务需要在你的电脑上安装运行环境(如 Node.js 18+)。各客户端的配置文件位置不同,请参考客户端文档。

安装包
pypiwebull-openapi-mcp1.2.6

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具,维护者暂未提供工具列表。

详细介绍

Webull OpenAPI MCP Server

Python 3.10+ License: Apache 2.0

Webull OpenAPI 的 MCP 服务 — 让 AI 助手(Cursor、Claude Desktop、Kiro 等)能够安全地访问 Webull 交易和市场数据。


⚠️ 免责声明

此工具提供的信息仅供参考,不构成投资建议。交易涉及风险,请谨慎决策。

完整免责声明请参阅 DISCLAIMER.md。


功能

  • 多地区支持 — 支持美国、香港、日本、新加坡、马来西亚、英国、墨西哥、巴西和南非地区,并提供地区专属的订单类型、交易时段和验证
  • 市场数据 — 为股票、期权、期货、加密货币和事件合约提供实时快照、逐笔数据、报价(深度)、足迹图和 OHLCV K 线
  • NOII 数据 — 为美国股票开盘和收盘竞价提供净订单失衡指标 K 线和快照
  • 筛选器 — 涨幅榜、跌幅榜、成交最活跃榜、市场板块、高股息榜和 52 周新高/新低榜
  • 自选列表 — 创建、管理和查询用户自选列表及金融工具
  • 社区(仅限美国)— 创建帖子和评论、查看热门股票、按代码浏览帖子、查看帖子详情,以及列出自己的帖子
  • 基本面数据 — 公司简介、分析师评级和目标价
  • 股票和基金基本面 — 资金流向、SEC 文件、财报/分红日历、预期 EPS、行业比较,以及完整基金数据(评级、表现、配置、持仓、简介、分红、拆分、净值、文件)
  • 财务报表 — 财务预警、指标、损益表、资产负债表和现金流量表
  • 交易 — 为股票、期权、期货、加密货币和事件合约下单、修改和取消订单
  • 组合订单 — OTO、OCO、OTOCO 组合订单(仅限美国)
  • 期权策略 — 多腿期权策略:垂直价差、跨式、宽跨式、蝶式、鹰式等(仅限美国)
  • 算法订单 — TWAP、VWAP、POV 算法订单(仅限美国)
  • 风险控制 — 按市场设置名义金额上限(USD/HKD/CNH/JPY)、数量上限和代码白名单
  • 自动账户解析 — 根据资产类型(股票、期货、加密货币、事件)自动选择正确账户
  • 审计日志 — 记录所有订单操作以满足合规要求
  • 双重身份验证支持 — 为启用了双重身份验证的账户提供交互式身份验证流程

示例提示词

以下是一些可与 AI 助手搭配使用的提示词:

市场数据

  • 显示 AAPL 过去 5 天的日线数据
  • 获取 AAPL、MSFT 和 GOOGL 的实时快照
  • TSLA 当前的买价/卖价是多少?
  • 显示 NVDA 的 1 分钟逐笔数据
  • 显示 AAPL 开盘前的 NOII 数据

筛选器

  • 今天涨幅最大的股票有哪些?
  • 显示盘前跌幅最大的股票
  • 目前交易最活跃的股票有哪些?
  • 显示市场板块概览
  • 列出高股息股票
  • 哪些股票创下了 52 周新高?

关注列表

  • 显示我的所有关注列表
  • 创建一个名为“Tech Stocks”的新关注列表
  • 将 AAPL 和 MSFT 添加到我的关注列表
  • 我的关注列表中有哪些股票?

社区

  • 目前社区热门股票有哪些?
  • 显示社区近期关于 NVDA 的帖子
  • 发布一条带有 AAPL 标签的帖子:“Great earnings report!”
  • 列出我的社区帖子

基本面与分析师

  • 介绍一下 NVDA 的公司概况
  • 分析师对 AAPL 的评级如何?
  • 分析师给出的 TSLA 目标价是多少?
  • 显示 AAPL 的资金流向
  • 获取 TSLA 的财报日历
  • 显示 NVDA 的行业对比
  • QQQ 的主要持仓和基金表现如何?

财务报表

  • 显示 AAPL 最新的利润表
  • 获取 TSLA 最近 4 个季度的资产负债表
  • NVDA 的现金流量表是什么样的?
  • 显示 MSFT 的财务指标

账户与投资组合

  • 我的账户余额和购买力是多少?
  • 显示我当前的所有持仓
  • 列出我关联的所有账户

股票交易

  • 以 $250 的价格买入 100 股 AAPL,设置限价单
  • 以市价单卖出 50 股 TSLA
  • 下单前,预览以 $450 的价格买入 200 股 MSFT 的限价单

期权交易

  • 买入 1 份 AAPL 看涨期权,行权价 $250,到期日为 2026-04-17,限价 $5.00
  • 买入 1 份 TSLA 看跌期权,行权价 $200,到期日为 2026-05-15

期权市场数据

  • 获取 AAPL260522C00300000 的快照
  • 显示 TSLA251219C00450000 的逐笔数据
  • 获取 AAPL260522C00300000 的日线数据
  • 列出到期日在 2026-06-01 之后的 AAPL 可用期权合约

订单管理

  • 显示我过去 7 天的订单历史
  • 我当前有哪些未结订单?
  • 取消 ID 为 abc123 的订单

香港市场

  • 以 HKD 500 的价格买入 100 股腾讯(00700),设置增强限价单
  • 以 HKD 510 的价格为 00700 下达 200 股竞价限价单

前提条件

  1. Webull 开发者账户 — 在以下网址注册:
  2. API 凭据 — 获取你的 App Key 和 App Secret
  3. 市场数据订阅 — 订阅行情以获取市场数据:
  4. Python 3.10+
  5. uv(推荐)— 安装指南

快速开始

步骤 1:配置凭据

启动服务前,必须配置 API 凭据。请选择以下任一种方式:

选项 A:MCP 客户端配置(推荐用于生产环境)

通过 MCP 客户端配置中的 env 字段添加凭据(Kiro、Cursor、Claude Desktop 等):

{
  "mcpServers": {
    "webull": {
      "command": "uvx",
      "args": ["webull-openapi-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_app_key",
        "WEBULL_APP_SECRET": "your_app_secret",
        "WEBULL_REGION_ID": "us",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

选项 B:.env 文件

# Create a .env file interactively:
uvx webull-openapi-mcp init

# Or manually create .env with:
# WEBULL_APP_KEY=your_app_key
# WEBULL_APP_SECRET=your_app_secret
步骤 2:身份验证(双重身份验证)

如果你的账户要求进行双重身份验证,请运行身份验证命令,并在 Webull 移动应用中批准:

uvx webull-openapi-mcp auth

令牌有效期为 15 天,并会自动刷新。你只需执行一次(或在令牌过期时再次执行)。

步骤 3:启动服务
uvx webull-openapi-mcp serve

完成。你的 AI 助手现在可以访问 Webull 交易和市场数据。


安装选项

选项 1:uvx(推荐)

无需安装。uvx 会直接从 PyPI 下载并运行软件包:

uvx webull-openapi-mcp serve
选项 2:pip
pip install webull-openapi-mcp
webull-openapi-mcp serve
选项 3:本地开发
git clone https://github.com/webull-inc/webull-openapi-mcp.git
cd webull-openapi-mcp
uv sync
uv run python -m webull_openapi_mcp serve

客户端配置

Kiro / Cursor / Claude Desktop / Claude Code

将以下内容添加到 MCP 配置中:

使用环境变量:

{
  "mcpServers": {
    "webull": {
      "command": "uvx",
      "args": ["webull-openapi-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_app_key",
        "WEBULL_APP_SECRET": "your_app_secret",
        "WEBULL_REGION_ID": "us",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

使用 .env 文件(本地开发):

{
  "mcpServers": {
    "webull": {
      "command": "uv",
      "args": [
        "run", "--directory", "/path/to/webull-openapi-mcp",
        "python", "-m", "webull_openapi_mcp", "serve",
        "--env-file", "/path/to/.env"
      ]
    }
  }
}

配置

变量说明默认值
WEBULL_APP_KEYApp Key(必填)—
WEBULL_APP_SECRETApp Secret(必填)—
WEBULL_ENVIRONMENTuat(沙盒)或 produat
WEBULL_REGION_IDus、hk、jp、sg、my、uk、mx、br 或 zaus
WEBULL_TOOLSETS启用的工具类别(逗号分隔)。有效值:account、market-data、trading、instrument(全部启用)
WEBULL_MAX_ORDER_NOTIONAL_USD美国市场的最大订单金额(USD)10000
WEBULL_MAX_ORDER_NOTIONAL_HKD香港市场的最大订单金额(HKD)80000
WEBULL_MAX_ORDER_NOTIONAL_CNH中国市场的最大订单金额(CNH)70000
WEBULL_MAX_ORDER_NOTIONAL_JPY日本市场的最大订单金额(JPY)1500000
WEBULL_MAX_ORDER_QUANTITY最大订单数量1000
WEBULL_SYMBOL_WHITELIST允许的代码(逗号分隔)(不限制)
WEBULL_TOKEN_DIR令牌存储目录./conf/
WEBULL_AUDIT_LOG_FILE审计日志文件路径仅输出到 stderr
WEBULL_LOG_LEVELSDK 日志级别WARNING

注意: WEBULL_REGION_ID=us 表示 Webull US(developer.webull.com),WEBULL_REGION_ID=hk 表示 Webull Hong Kong(developer.webull.hk),WEBULL_REGION_ID=jp 表示 Webull Japan(developer.webull.co.jp),WEBULL_REGION_ID=sg 表示 Webull Singapore(developer.webull.com.sg),WEBULL_REGION_ID=my 表示 Webull Malaysia(developer.webull.com.my),WEBULL_REGION_ID=uk 表示 Webull UK(developer.webull-uk.com),WEBULL_REGION_ID=mx 表示 Webull Mexico(developer.webull.com.mx),WEBULL_REGION_ID=br 表示 Webull Brazil(developer.webull.com.br),WEBULL_REGION_ID=za 表示 Webull South Africa(developer.webull.co.za)。

完整配置模板请参阅 .env.example。


可用工具

Market Data
CategoryToolsRegion
Stockget_stock_tick, get_stock_snapshot, get_stock_quotes, get_stock_footprint, get_stock_bars, get_stock_bars_single, get_stock_noii_bars, get_stock_noii_snapshotAll
Futuresget_futures_tick, get_futures_snapshot, get_futures_depth, get_futures_bars, get_futures_footprintUS, HK
Cryptoget_crypto_snapshot, get_crypto_barsUS
Optionget_option_tick, get_option_snapshot, get_option_barsUS, HK, JP
Eventget_event_tick, get_event_snapshot, get_event_depth, get_event_barsUS
Market Insightsget_market_sentiment, get_stock_unusual_activities, get_institution_identifier, get_institution_holdings, get_institution_holding_changes, get_insider_transactions, get_insider_holdings, get_macroeconomic_calendarUS
Newssearch_news, get_news_detail, get_stock_newsUS
Screenerget_gainers_losers, get_most_active, get_market_sectors, get_market_sectors_detail, get_high_dividend, get_52_week_high_lowAll
Watchlistget_watchlists, create_watchlist, update_watchlist, delete_watchlist, get_watchlist_instruments, add_watchlist_instruments, remove_watchlist_instruments, update_watchlist_instrumentsAll
Communitycreate_community_post, create_community_comment, get_community_hot_stocks, get_community_posts, get_community_post_detail, get_my_community_postsUS
Fundamental & Instrument
CategoryToolsRegion
Instrumentget_instruments, get_option_contracts, get_futures_instruments, get_futures_products, get_crypto_instruments, get_event_series, get_event_instruments, get_event_categories, get_event_eventsvaries
Fundamentalget_company_profile, get_analyst_rating, get_analyst_target_priceAll
Stock Fundamentalsget_stock_capital_flow, get_stock_filings, get_stock_earnings_calendar, get_stock_dividend_calendar, get_stock_forecast_eps, get_stock_industry_comparisonAll
Fund Fundamentalsget_fund_rating, get_fund_performance, get_fund_allocation, get_fund_holdings, get_fund_brief, get_fund_dividends, get_fund_splits, get_fund_net_value, get_fund_filesAll
Financial Statementsget_financial_alert, get_financial_indicators, get_income_statement, get_balance_sheet, get_cash_flowAll
Trading
CategoryToolsRegion
Accountget_account_listAll
Assetsget_account_balance, get_account_positions, get_account_position_details (JP only)All
Stock Orderplace_stock_order, preview_stock_order, replace_stock_orderAll
Combo Orderplace_stock_combo_order (OTO/OCO/OTOCO)US
Option Orderplace_option_single_order, preview_option_order, replace_option_orderUS, HK
Option Strategyplace_option_strategy_orderUS
Algo Orderplace_algo_order (TWAP/VWAP/POV)US
Futures Orderplace_futures_order, replace_futures_orderUS, HK
Crypto Orderplace_crypto_orderUS
Event Orderplace_event_order, replace_event_orderUS
Ordercancel_order, get_order_history, get_open_orders, get_order_detailAll
区域差异
功能USHKJPSGMYUKMXBRZA
股票交易YesYesYesYesYesYesYesYesYes
期权交易YesYesNoNoNoNoNoNoNo
期货交易YesYesNoNoNoNoNoNoNo
加密货币交易YesNoNoNoNoNoNoNoNo
事件合约YesNoNoNoNoNoNoNoNo
组合订单YesNoNoNoNoNoNoNoNo
期权策略YesNoNoNoNoNoNoNoNo
算法订单YesNoNoNoNoNoNoNoNo
筛选器YesYesYesYesYesYesYesYesYes
观察列表YesYesYesYesYesYesYesYesYes
基本面(公司/分析师)YesYesYesYesYesYesYesYesYes
股票/基金基本面YesYesYesYesYesYesYesYesYes
财务报表YesYesYesYesYesYesYesYesYes
NOII(竞价失衡)YesYesYesYesYesYesYesYesYes
市场USUS, HK, CNUS, JPUSUSUSUSUSUS
工具类别US_STOCK, US_ETFUS_STOCK, US_ETF, HK_STOCK, CN_STOCKUS_STOCK, US_ETFUS_STOCK, US_ETFUS_STOCK, US_ETFUS_STOCK, US_ETFUS_STOCK, US_ETFUS_STOCK, US_ETFUS_STOCK, US_ETF
订单类型LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, TRAILING_STOP_LOSS, etc.LIMIT, MARKET, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, etc.JP market: LIMIT, MARKET — US market: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMITMARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMITMARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMITMARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMITMARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMITMARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMITMARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT
有效期限DAY, GTCUS market: DAY, GTC, GTD — HK market: DAY, GTC — CN market: DAYJP market: DAY — US market: DAY, GTC, GTDDAY, GTCDAY, GTCDAY, GTCDAY, GTCDAY, GTCDAY, GTC
交易时段ALL, CORE, NIGHTCORE, ALL_DAY, NIGHT, ALLCORE, ALL, NIGHT, ALL_DAYNIGHT, ALL, CORE, ALL_DAYNIGHT, ALL, CORE, ALL_DAYNIGHT, ALL, CORE, ALL_DAYNIGHT, ALL, CORE, ALL_DAYNIGHT, ALL, CORE, ALL_DAYNIGHT, ALL, CORE, ALL_DAY
JP 订单字段——account_tax_type required (GENERAL or SPECIFIC); margin_type (ONE_DAY or INDEFINITE) and position_intent optional margin-account-only fields; close_contracts optional——————

注: 筛选器(涨幅榜/跌幅榜/活跃榜)、基本面(公司/分析师)和 NOII 目前仅支持查询 US 股票数据(US_STOCK 类别)。股票/基金基本面、财务报表以及扩展筛选器(板块/股息/52 周)适用于所有区域;支持的 category 值因端点而异(通常为 US_STOCK、HK_STOCK、CN_STOCK、JP_STOCK)。观察列表支持 US 股票和 HK 股票。


命令行命令

如果通过 pip 安装:

webull-openapi-mcp --version                        # Show version
webull-openapi-mcp init [--env-file PATH]           # Initialize .env configuration
webull-openapi-mcp init --app-key KEY --app-secret SECRET --environment prod
webull-openapi-mcp auth [--env-file PATH]           # Authenticate (2FA accounts)
webull-openapi-mcp serve [--env-file PATH]          # Start MCP server
webull-openapi-mcp status [--env-file PATH]         # Show configuration status
webull-openapi-mcp tools [--env-file PATH]          # List available tools

如果使用 uvx(在命令前加上 uvx):

uvx webull-openapi-mcp auth
uvx webull-openapi-mcp serve
uvx webull-openapi-mcp status

如果在本地开发(在命令前加上 uv run python -m webull_openapi_mcp):

uv run python -m webull_openapi_mcp auth
uv run python -m webull_openapi_mcp serve

所有命令均接受 --env-file PATH,用于指定自定义 .env 文件位置(默认:当前目录中的 .env)。


安全

  • 切勿向 AI 模型分享 AK/SK — 不要将 App Key 或 App Secret 粘贴到聊天提示词、AI 助手或任何大模型对话中。这些凭据只能通过环境变量或 .env 文件配置,绝不能以纯文本形式暴露给模型。
  • 优先使用 env,而非 .env 文件 — 通过 MCP 客户端的 env 字段(在 mcp.json 中)传递凭据,而不是使用工作区中的 .env 文件。env 字段会将凭据注入为进程环境变量,AI 模型无法访问这些变量。AI 助手可能通过 IDE 文件访问功能读取工作区中的 .env 文件。
  • 凭据隔离 — AK/SK 仅在 MCP 服务进程内部用于 SDK 初始化和请求签名。它们绝不会出现在工具输出、日志或错误消息中。
  • 交易前请审核 — 确认前,务必审核 AI 提出的订单详情。下单前请使用 preview_stock_order / preview_option_order。
  • 使用工具集筛选 — 设置 WEBULL_TOOLSETS=account,market-data,即可完全禁用交易工具(如果你只需要只读访问权限)。有效的工具集:account、market-data、trading、instrument。
  • 默认使用沙盒 — 服务默认使用 UAT(沙盒)环境。进行实盘交易时,必须显式设置 WEBULL_ENVIRONMENT=prod。
  • 依赖项安全 — fastmcp 固定为版本 3.0.2,webull-openapi-python-sdk 固定为 3.0.4。用户有责任监控并更新第三方依赖项,以获取安全补丁。升级前请查看发行说明。

故障排除

需要进行 2FA 身份验证
# If installed via pip:
webull-openapi-mcp auth

# If using uvx:
uvx webull-openapi-mcp auth

# If local development:
uv run python -m webull_openapi_mcp auth

在 Webull 应用中批准请求,然后启动服务。

设备未注册
  1. 打开 Webull 移动应用,使用 API 账户登录并完成设备注册
  2. 然后进行身份验证:
# If installed via pip:
webull-openapi-mcp auth

# If using uvx:
uvx webull-openapi-mcp auth
市场数据 401/403

订阅行情:

令牌已过期
rm -rf ./conf/token.txt

# Then re-authenticate:
webull-openapi-mcp auth       # pip
uvx webull-openapi-mcp auth   # uvx
Windows:错误消息出现乱码

在 Windows 上,如果控制台编码不是 UTF-8,身份验证错误消息可能会显示乱码。服务会自动检测控制台编码,并在非 UTF-8 终端上回退为仅输出 ASCII 字符。如果仍然看到乱码,请运行:

chcp 65001

这会在启动服务前将 Windows 控制台切换为 UTF-8。


项目结构

webull-openapi-mcp/
├── webull_openapi_mcp/
│   ├── __init__.py         # Package version
│   ├── __main__.py         # python -m entry point
│   ├── cli.py              # CLI commands (init, auth, serve, status, tools)
│   ├── server.py           # MCP server setup and tool registration
│   ├── sdk_client.py       # Webull SDK adapter (ApiClient, TradeClient, DataClient)
│   ├── config.py           # Configuration loading and validation
│   ├── region_config.py    # Region-specific settings (US, HK, JP, SG, MY, UK, MX, BR, ZA)
│   ├── guards.py           # Order validation (price, quantity, notional, region rules)
│   ├── audit.py            # Audit logging for order operations
│   ├── errors.py           # Exception definitions and SDK error handling
│   ├── formatters.py       # Response formatting with disclaimer
│   ├── constants.py        # Enum constants (sides, order types, strategies)
│   └── tools/
│       ├── __init__.py     # Tool registration exports
│       ├── market_data/
│       │   ├── stock.py    # Stock market data (snapshot, quotes, bars, tick, footprint, NOII)
│       │   ├── option.py   # Option market data (tick, snapshot, bars)
│       │   ├── futures.py  # Futures market data
│       │   ├── crypto.py   # Crypto market data
│       │   ├── event.py    # Event contract market data
│       │   ├── screener.py # Gainers/losers, most active, market sectors, high dividend, 52-week high/low
│       │   ├── watchlist.py# Watchlist CRUD and instrument management
│       │   ├── community.py # Community posts, comments, hot stocks
│       │   ├── fundamental.py # Company profile, analyst data; stock & fund fundamentals (US/HK/JP)
│       │   └── financial.py   # Financial statements: alert, indicators, income, balance sheet, cash flow (US/HK/JP)
│       └── trading/
│           ├── account.py       # Account list
│           ├── assets.py        # Balance, positions
│           ├── instrument.py    # Instrument lookup
│           ├── order.py         # Order query, cancel (shared across asset types)
│           ├── stock_order.py   # Stock order place, preview, replace
│           ├── option_order.py  # Option single-leg and strategy orders
│           ├── futures_order.py # Futures order place, replace
│           ├── crypto_order.py  # Crypto order place
│           └── event_order.py   # Event contract order place, replace
├── tests/                  # Unit and property-based tests
├── conf/                   # Token storage (auto-generated)
├── .env.example            # Configuration template
├── DISCLAIMER.md           # Full disclaimer
├── pyproject.toml          # Package configuration
└── LICENSE                 # Apache 2.0

许可证

Apache License 2.0 — 详情请参阅 LICENSE。

评论

支持 Markdown

第一次接触 MCP?

从协议是什么,到在客户端里装上第一个服务,这几条回答覆盖了大多数入门问题。

一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。