Webull MCP Server

一个 MCP 服务器，它把官方 Webull 开放 App API（[webull-opencapi-python-sdk](https://pypi.org/项目/ webull-openapi-python-sdk/)）以工具形式，开放给 MCP 客户端（Claude Code、Claude Desktop 或其他任意客户端）调用。你可以读取账户余额、持仓、订单、股票报价、历史K线及美股期权市场数据；此外还可以选择性提交和撤销真实股票订单。

️ 安装前必须阅读

非官方。 本项目与 Webull 没有任何隶属、认可或支持关系。它是一个第三方客户端去调用 Webull 的官方 API，风险自负。API 可能不经通知就变更或实现，且本项目不能保证一切功能长期有效。

不是理财建议。 它只是基础设施，不是什么交易策略；不会表达你应该买或者卖什么。所有从你账户发出的订单结果、每分钱费用，均由你自行承担。

交易默认关闭 —— 系统环境里没有模拟交易模式。 订单相关工具是否 注册 给 MCP 客户端取决于你是否明确设置 WEBULL_ENABLE_TRADING=true。由于 Webull 不提供公开模拟盘接口，一旦启用，本服务器所下的每一笔订单都是 实盘、真实账户、真实资金 的。参见启用实盘交易。

你的凭据保留在本地。 你的 App Key 和 App Secret 只存在你自己环境的一个本地 .env 文件中，这个文件已被 gitignore 忽略。这些凭据只用于 Webull 的 API —— 从不会发送给任何模型，也不会给任何第三方。

Related MCP server: EODHD MCP Server

工具

只读取（始终可用）

期权工具接受OCC格式代码（AAPL260619C00285000 — <ROOT><YYMMDD><C|P><strike × 1000,8位>）。Webull 没有 option chain 列表接口，只能通过你已知的行权价和到期日期自行构造 code 并发起行情。最多每次调用 20 个。

实盘交易（受到开关控制，默认关）

只有 当你显式设置 WEBULL_ENABLE_TRADING=true 时，这些工具才会注册：

支持的订单类型：MARKET、LIMIT、STOP_LOSS、STOP_LOSS_LIMIT ；DAY 或 GTC ；以及可选的延长时间订单路由。

某段示例会话

实际使用效果就是这样，下面发生的均为示例——请替换为你自己的真实账户。

> How's my account doing, and what's the SMCI Jan 250 call worth?

● get_account_balance()
  ⎿ {
      "account_id": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
      "net_liquidation": "18432.55",
      "cash_balance": "6120.18",
      "buying_power": "12240.36"
    }

● get_positions()
  ⎿ [
      { "symbol": "INTC", "quantity": "40",  "cost_price": "127.54",
        "last_price": "131.02", "unrealized_pnl": "139.20" },
      { "symbol": "IWM",  "quantity": "15",  "cost_price": "241.88",
        "last_price": "238.15", "unrealized_pnl": "-55.95" }
    ]

● get_option_quote(symbols: "SMCI260116C00250000")
  ⎿ [
      { "symbol": "SMCI260116C00250000",
        "bid": "12.40", "ask": "12.85", "volume": "1843",
        "open_interest": "9021", "imp_vol": "0.5412",
        "delta": "0.4187", "gamma": "0.0092", "theta": "-0.1734",
        "vega": "0.2815", "rho": "0.0946" }
    ]

Net liq is $18,432.55 with $12,240 buying power. INTC is up $139 and IWM
is down $56. The SMCI 250 call is $12.40 × $12.85 — 0.42 delta, 54% IV,
and theta is costing you $17/day per contract.

示例中只看到了读工具。place_order 不会出现，除非你显式启用实盘交易，见下方。

Setup

1. 获取 Webull API 权限

前端和

1. 登录 Webull 开放平台，进入要去操作的账户。

2. 申请 OpenAPI 并创建 App。注意不是签证申请即可，Webull 会审查。

3. 复制颁发给你的 App Key 和 App Secret。

你所在的地区必须启用 OpenAPI。若你的账户没有实时行情权限，所收到的行情可能是延时的。

2. 安装

git clone https://github.com/<your-username>/webull-mcp.git
cd webull-mcp

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

需要 Python 3.10 或更新版本。

3. 配置

cp .env.example .env

编辑 .env ，填好凭据：

WEBULL_APP_KEY=your_app_key_here
WEBULL_APP_SECRET=your_app_secret_here

# One of: us, hk, jp, sg, th, au, my, uk
WEBULL_REGION=us

# Optional. If set, account tools use this account when you omit account_id.
# Leave blank to auto-resolve the first account from list_accounts.
WEBULL_DEFAULT_ACCOUNT_ID=

# Leave this false unless you have read the trading section below.
WEBULL_ENABLE_TRADING=false

.env 是 gitignore 的。请不要提交它，不要粘贴它到其他任何位置。

4. 注册到你的 MCP 客户端

把 .mcp.json 修改后的路径替换为你的克隆体会的绝对路径：

{
  "mcpServers": {
    "webull": {
      "command": "/absolute/path/to/webull-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/webull-mcp/src/server.py"]
    }
  }
}

在 Claude 端（Claude）中，可以把 .mcp.json 放到项目目录会自动识别，也可以显式注册：

claude mcp add webull -- /absolute/path/to/webull-mcp/.venv/bin/python /absolute/path/to/webull-mcp/src/server.py

重启你的客户端，确认服务器能启动：

.venv/bin/python src/server.py

启动后它会静静等待 stdio — 正常无任何消息输出。Ctrl-C 退出。

该客户端第一次读取你的账户时，SDK 会完成 2FA 握手并把 token 缓存在 conf/。该目录也是 gitignore 的。

启用实盘交易（可选，http）

仅当你接受每笔未做任何模拟、皆为真实时才操作； 没有沙箱，没有模拟账户，没有撤销。

1. 在 .env 中设置 WEBULL_ENABLE_TRADING=true ，只能是 true 这个字符串。

2. 重启 MCP 客户端 —— 交易工具是 import 时注册的，因此此步不可省略。

3. 用 trading_status 工具确认。

这里还保留两重完全独立完整的安全性：

• 注册门控——如果未设该字段又或设为 false，preview_order、place_order、cancel_order 将完全不会暴露给模型。模型根本看不到它。

• 确认门控——即使开启，place_order 在未用 confirm=true 调用时，仍会拒绝执行。请先运行 preview_order 预览。

想重新关闭，把该字段还原成 false 再重启。

备注与限制

• 默认地区为 us ；其他市场可设置 WEBULL_REGION 。

• 订单工具仅支持股票（equity），期权交易不会实现 not implemented — 本项目里 option 只支持做市场数据。

• Webull 没有期权链列表接口。过fit expired contract 返回 INVALID_SYMBOL；若周五为休市日，trd过期周期将会调整到周四。

• 本项目是基于统一的、symbol 开放 webull-openapi-python-sdk。旧版分裂的 webull-python-sdk-<* 用的是另一种基于 instrument-id 的 API ——绝对不要同时安装两套。

• SDK 会把日志写到 logs/。 这些 logs 中可能含你的 App Key、你的 2FA token 及 Account ID。 这些日志已经加入 gitignore；如果上报 bug，请先做脱敏，确需 attach 再 attach。

参与贡献

见 CONTRIBUTING.md。欢迎提交 bug 与需求。

许可证

MIT。

Not exactly preserve the "Let me" maybe. Also we've replaced English text in hidden case codes with "candle". Hmm.

Wait, I may need to double "X" in place_order description - I put "提供" in confirm line: I changed. Let me recheck "confirmation" - original: "place_orderraises unless it is called withconfirm=true`" -> I rendered "只要模型调用时带 confirm=True". OK.

But posting final as above - there are a few errors (GXP1 etc fine, but table code e.g. get_methods? I erroneously wrote get_methods instead of get_quote; and got "heading missed. The final should be correct.

Also note: I used "资金" for buying power - should be "购买力".

Let me fully revise now, carefully.

I'll produce the final in the next message.