Webull MCP Server

Сервер MCP, который предоставляет официальный Webull OpenAPI (webull-openapi-python-sdk) в виде инструментов, которые может вызывать MCP-клиент — Claude Code, Claude Desktop или любой другой. Читает балансы счетов, позиции, ордера, биржевые котировки, исторические бары и данные по американским опционам; опционально — размещает и отменяет реальные биржевые ордера.

⚠️ Прочтите перед установкой

Неофициальный проект. Этот проект не связан с Webull, не одобрен и не поддерживается Webull. Он обращается к Webull OpenAPI как сторонний клиент, на ваш страх и риск. API может измениться или сломаться без предупреждения, и ничто здесь не гарантирует стабильность работы.

Не финансовый совет. Это инженерная инфраструктура, а не торговая стратегия. Здесь нет мнения о том, что вам следует покутaть or продaвtть. Вы неодинко осКак один несёте полную ответственость за каждый ордер, который уходит с вашего счtа, и за каждый доллар, кото he стоил бы.

Торговая по умолчанию отключена — и бумasногорежима нет. Торговые инструменты даже регистрируются u MCP-клиента, если вы явно не зададите WEBULL_ENABLE_TRADING=true. Webull не публикует никакого эндпо:нта для буманой тогли, пThis значит, как только фича будет вклчена, каждый ордер, размещинный этим сервером, будет реальным, на реальные деньги, на реальном счёте. СМ.: Вклвчение живой тогравли.

Ваши credentials остаются на хорошо месте. Ваши App Key и App Secret ханятся только в лоlocal.файле .env, кото to is gitignored. Они отправляются только в API Webull — никогда в модель, никогда трratio.

Related MCP server: Toss Invest MCP

Инструменты

Только чтение (всегда доступно)

Опtsинструменты принима символыOCC (SY/DEBUG/…) — <ROOT><YXMMDD><C|Р×1000, 8 digits. У Webull н:т эndпо: conchain-listing, поэтому соstтай кандид→ симпров. известно roadmap и expireи, пря запtrash их. Up to 20per call.

Жв trading (gate, off по умол)

Рegистриваются только когда WEBULL_ENABLE_TRADING=true:

Supported type: MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT; DAY/GTC; extension hours.

Examplesession

Так выглядит использование from an MCP client. Values below are illustrative vs your own.

> 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.

Above, only read-only instruments. place_order is unavailable unless you explicit enable trading — см. Enabling live trading.

Setup

1. Get Webull API credentials

1. Go to Webull Developer portal and sign с Webull.

2. Apply for OpenAPI access and create app. Approval is not instant — Webull reviews req.

3. Copy App Key и App Secret we can.

Your account must have OpenAPI enabled for region. Real-time market data requests may require market-data entitlement; if none, quotes may be delayed.

2. Install

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

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

Requires Python3.10 or newer.

3. Configure

cp .env.example .env

Edit .env and fill your credentials:

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 is gitignored. Don't commit, don't paste.

4. Register at MCP client

Edit .mcp.json to replace placeholder paths to absolute path:

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

For Claude Code, drop .mcp.json into project or register:

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

Restart client. Verify server starts:

.venv/bin/python src/server.py

Should start and wait — no output is normal. Ctrl-C exit.

First account call: 2FA handshake and token as conf/. Gitignored.

Enabling live trade (optional)

Деwidth do only if you accept live trades. No sandbox, no paper, no undo.

1. Set WEBULL_ENABLE_TRADING=true in .env — exactly true.

2. Restart MCP client. Trading tools register at import time, restart needed.

3. Confirm with trading_status.

Safety layers:

• Registry — with false, place_order etc not exposed. Model can't call what it doesn't see.

• Confirmation — even enabled, place_order raises without confirm=True. Run preview first.

Defense. Disable, set false, restart.

Limitations

• Region defaults us, set WEBULL_REGION for others.

• Orders cover equities only — no option trading; option support is market data only.

• Webull no option chain endpoint. Build OCC symbols yourself. Expired returns INVALID_SYMBOL, Friday expirations move to Thursday on holiday.

• Uses unified symbol-based webull-openapi-python-sdk. Older split webull-python-sdk-* packages differ, don't install both.

• SDK logs into logs/. Logs contain your App Key, 2FA token, account IDs. Gitignored; never attach without redaction.

Contributing

See CONTRIBUTING.md. Bug reports and PRs welcome.

License

MIT.