Webull AU OpenAPI MCP

A slim MCP server for the Webull Australia OpenAPI. It exposes exactly what the AU platform supports — US stock and ETF market data and trading — and nothing else. Region is hardcoded to au; there is no multi-region, options, futures, crypto, event-contract, combo, strategy or algo code.

Built on fastmcp and the official webull-openapi-python-sdk (≥ 2.0.12, which is the first line to bundle AU production endpoints).

For reference only; not investment advice. Trading involves risk. Review every order before confirming.

Install

cd webull-au-mcp
uv sync            # or: pip install -e .

Configure

webull-au-mcp init          # writes .env
# edit .env → set WEBULL_APP_KEY / WEBULL_APP_SECRET
webull-au-mcp status        # sanity-check config

For a zero-setup trial, use a public UAT test account from the AU SDK docs (no application, no 2FA):

WEBULL_ENVIRONMENT=uat
WEBULL_APP_KEY=c8d29a52a41c03cb76ebe1f680bada3c
WEBULL_APP_SECRET=40424c891fca1aa68c0aeef862de2ee7
WEBULL_ACCOUNT_ID=1234113618547593216

Configuration

Variable	Description	Default
WEBULL_APP_KEY	App key (required)	—
WEBULL_APP_SECRET	App secret (required)	—
WEBULL_ENVIRONMENT	uat (sandbox, no 2FA) or prod (live)	uat
WEBULL_ACCOUNT_ID	Default account for tools that need one	—
WEBULL_TOOLSETS	account, market-data, instrument, trading (comma-sep)	account,market-data,instrument
WEBULL_MAX_ORDER_NOTIONAL_USD	Max single-order value (USD)	10000
WEBULL_MAX_ORDER_QUANTITY	Max single-order share quantity	1000
WEBULL_SYMBOL_WHITELIST	Allowed symbols (comma-sep); empty = any	—
WEBULL_TOKEN_DIR	2FA token store directory	./conf/
WEBULL_AUDIT_LOG_FILE	Append order audit records here	stderr only
WEBULL_LOG_LEVEL	SDK log level	WARNING

Trading is off by default. The default toolset is read-only. Add trading to WEBULL_TOOLSETS to enable order placement, ideally alongside a tight WEBULL_SYMBOL_WHITELIST and notional/quantity caps.

Authenticate (prod only)

UAT test tokens need no 2FA. For a live account:

webull-au-mcp auth      # approve the request in your Webull app
webull-au-mcp serve

Client configuration

{
  "mcpServers": {
    "webull-au": {
      "command": "uvx",
      "args": ["--from", "/path/to/webull-au-mcp", "webull-au-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_app_key",
        "WEBULL_APP_SECRET": "your_app_secret",
        "WEBULL_ENVIRONMENT": "prod",
        "WEBULL_TOOLSETS": "account,market-data,instrument,trading",
        "WEBULL_SYMBOL_WHITELIST": "AAPL,MSFT,VOO",
        "WEBULL_MAX_ORDER_NOTIONAL_USD": "5000"
      }
    }
  }
}

Pass credentials via the client's env field rather than a .env file in your workspace, so the model can't read them.

Docker

The image runs the server over HTTP transport (a long-running networked endpoint at http://<host>:8000/mcp), which suits a homelab far better than stdio.

cp .env.example .env      # fill in credentials
docker compose up -d --build

For a prod account, cache the 2FA token once (interactive) before starting — the token persists in the ./conf volume:

docker compose run --rm webull-au-mcp auth
docker compose up -d

Point an HTTP-capable MCP client at http://<homelab-ip>:8000/mcp. For a local stdio client instead of the networked service, run the image directly:

docker run -i --rm --env-file .env -e WEBULL_MCP_TRANSPORT=stdio webull-au-mcp:latest

Variable	Description	Default (image)
WEBULL_MCP_TRANSPORT	stdio, http, sse, streamable-http	http
WEBULL_MCP_HOST	Bind address (http transports)	0.0.0.0
WEBULL_MCP_PORT	Bind port (http transports)	8000
WEBULL_MCP_PATH	MCP endpoint path (http transports)	/mcp

Tools

Account (account): get_account_list, get_account_balance, get_account_positions

Instrument (instrument): get_instrument

Market data (market-data): get_stock_snapshot, get_stock_quotes, get_stock_tick, get_stock_bars

Trading (trading): preview_stock_order, place_stock_order, replace_stock_order, cancel_order, get_open_orders, get_order_history, get_order_detail

Order tools hardcode the AU invariants (market=US, instrument_type=EQUITY, entrust_type=QTY, combo_type=NORMAL) and auto-generate the client_order_id, so the model only supplies symbol, side, quantity, order type and price. Every order passes quantity, notional and whitelist guards before submission; rejected orders never reach the broker. place_stock_order returns the client_order_id you need for replace/cancel/get_order_detail.

Order types: MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT. Time in force: DAY, GTC.

CLI

webull-au-mcp init [--env-file PATH] [--force]
webull-au-mcp auth [--env-file PATH]
webull-au-mcp serve [--env-file PATH]
webull-au-mcp status [--env-file PATH]
webull-au-mcp tools [--env-file PATH]

AU-specific notes

• SDK ≥ 2.0.12 is required. Earlier releases (including the 2.0.5 the multi-region upstream pins) only bundle us/hk/jp endpoints, so an au client fails region resolution. UAT hosts are injected explicitly by this server regardless.
• The upstream server also registers screener/watchlist/fundamental tools. The AU API reference do