Webull MCP Server

An MCP server that exposes the official Webull OpenAPI (webull-openapi-python-sdk) as tools an MCP client — Claude Code, Claude Desktop, or any other — can call. Read account balances, positions, orders, stock quotes, historical bars, and US option market data; optionally place and cancel live equity orders.

---

⚠️ Read this before you install

Unofficial. This project is not affiliated with, endorsed by, or supported by Webull. It calls Webull's OpenAPI as a third-party client, at your own risk. The API can change or break without notice, and nothing here is guaranteed to keep working.

Not financial advice. This is plumbing, not a strategy. It has no opinion about what you should buy or sell. You are solely responsible for every order that leaves your account and every dollar it costs you.

Trading is disabled by default — and there is no paper mode. The order tools are not even registered with the MCP client unless you explicitly set WEBULL_ENABLE_TRADING=true. Webull publishes no paper-trading endpoint, so once enabled, every order this server places is live, with real money, on a real account. See Enabling live trading.

Your credentials stay on your machine. Your App Key and Secret live only in a local .env file, which is gitignored. They are sent only to Webull's API — never to the model, never to any third party.

---

Tools

Read-only (always available)

Tool	What it does
list_accounts	List accounts available to your credentials
get_account_balance	Cash, net liquidation, buying power
get_positions	Current holdings
get_open_orders	Working orders
get_order_history	Filled, cancelled, and past orders
get_instrument	Resolve a ticker to instrument metadata
get_quote	Real-time price snapshot (last, OHLC, volume)
get_history_bars	Historical OHLCV candles
get_option_quote	Snapshots for US option contracts — bid/ask, volume, open interest, IV, and all five Greeks
get_option_history_bars	Historical OHLCV bars for option contracts
get_option_tick	Tick-by-tick trades for a single option contract
trading_status	Reports whether live trading is enabled

Option tools take OCC-format symbols (AAPL260619C00285000 — <ROOT><YYMMDD><C|P><strike × 1000, 8 digits>). Webull has no chain-listing endpoint, so build candidate symbols from known strikes and expirations and quote them directly. Up to 20 per call.

Live trading (gated, off by default)

Registered only when WEBULL_ENABLE_TRADING=true:

Tool	What it does
preview_order	Validate an order without submitting — fees, buying-power impact, validation errors
place_order	Submit a live equity order. Additionally requires confirm=True
cancel_order	Cancel a working order by client_order_id

Supported order types: MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT; DAY or GTC; optional extended-hours routing.

---

Example session

What using it actually looks like from an MCP client. Values below are illustrative — substitute your own account.

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

Only read-only tools appear above. place_order is not available at all unless you explicitly enable trading — see Enabling live trading.

---

Setup

1. Get Webull API credentials

1. Go to the Webull Developer portal and sign in with the Webull account you want the server to access.
2. Apply for OpenAPI access and create an app. Approval is not instant — Webull reviews requests.
3. Copy the App Key and App Secret it issues.

Your account must have OpenAPI enabled for your region. Real-time market data may additionally require a market-data entitlement on your account; without one, 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 Python 3.10 or newer.

3. Configure

cp .env.example .env

Edit .env and fill in 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. Never commit it, and never paste its contents anywhere.

4. Register with your MCP client

Edit .mcp.json and replace the placeholder paths with the absolute path to your clone:

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

For Claude Code, either drop .mcp.json into a project directory where it will be auto-detected, or register it explicitly:

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

Restart your client. Verify the server starts:

.venv/bin/python src/server.py

It should start and wait on stdio — no output is correct. Ctrl-C to exit.

On the first call that touches your account, the SDK performs a 2FA handshake and caches a token under conf/. That directory is gitignored.

---

Enabling live trading (optional)

Only do this if you accept that every order is real. There is no sandbox, no paper account, and no undo.

1. Set WEBULL_ENABLE_TRADING=true in .env — the string must be exactly true.
2. Restart your MCP client. The trading tools are registered at import time, so a restart is required.
3. Confirm with the trading_status tool.

Two independent safety layers remain in place:

• Registration gate — with the flag unset or false, place_order, preview_order, and cancel_order are never exposed to the model at all. It cannot call a tool it cannot see.
• Confirmation gate — even when enabled, place_order raises unless it is called with confirm=True. Run preview_order first.

To disable again, set the flag back to false and restart.

---

Notes and limitations

• Region defaults to us. Set WEBULL_REGION for other markets.
• Order tools cover equities only — options trading is not implemented. Option support here is market data only.
• Webull exposes no option-chain listing endpoint. Build OCC symbols yourself. Expired contracts return INVALID_SYMBOL, and Friday expirations shift to Thursday when Friday is a market holiday.
• Built on the unified, symbol-based webull-openapi-python-sdk. The older split webull-python-sdk-* packages use a different, instrument-id-based API — do not install both.
• The SDK writes logs under logs/. These logs contain your App Key, your 2FA token, and your account IDs. They are gitignored; never attach one to a bug report without redacting it first.

Contributing

See CONTRIBUTING.md. Bug reports and PRs are welcome.

License

MIT.