Webull MCP Server

An MCP server that exposes the Web official Webull OpenAPI (webull-openapi-python-sdk) as tools MCP client (Claude Code, Claude Desktop, or other) may call. It reads account balances, positions, orders, stock quotes, historical bars, and US option market data; optionally, live equity orders can be placed and canceled.

️ Installation requirements

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

Not investment strategy that investment recommendations. This is plumbing, not a strategy. It has no opinion on whether you should buy or sell; you are fully responsible for every order that leaves your account and every cost it creates.

Trading is disabled by default, and there is no paper mode. The order tool calculates not even registered with the MCP client unless you explicitly set WEBULL_ENABLE_TRADING=**true. Webull does not provide any paper trading endpoint, so once enabled, all orders placed by this server are executed live, with real money, in a real environment. See enabling live trading.

Your credentials remain on your machine. Your App Key and Secret are stored only in a local .env file, which is in the gitignore. It is transferred only to Webull's API — never to the model or any third party.

도구

Read-only (always available)

Option tools take OCC-format symbols (for example `<C|P><strike ×1000, 8 digits>). Since Webull does not provide a chain-listing endpoint, you must construct candidate symbols from known strike prices and maturity dates and query them directly. Up to 20 per call.

Trade (gated, off by default)

«등록 is done only when WEBULL_ENABLE_TRADING=true:

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

Example session

This is what it looks like from an MCP client. The values below are examples — replace with 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 in the example above. place_order is not available at all unless trading is explicitly enabled — see enabling live trading.

Setup

1. Obtain Webull API credentials.

Note: Webull Developer Go to Portal and sign in with the Webull account you want to access via server.

1. Apply for OpenAPI access and create an app. Approval is not immediate — Webull will review your request.

2. Copy the issued password.

Your account must have OpenAPI enabled for your region. Real-time market data may additionally require a market data entitlement; without it, quotes may be delayed.

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

2. Configure

cp .env.example .env

Edit .env to 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 this file, and never paste its contents anywhere.

4. Register MCP client

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

In GXP5

From Claude Code, you can either place .mcp.json into a project directory for automatic detection, 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, and verify that the server starts:

.venv/bin/python src/server.py

It should start and wait for stdio — ignoring no output is normal. You can exit with Ctrl-C.

When you first call REST and talk to your account, the SDK performs a 2FA handshake and stores the token in the conf/ directory. That directory is gitignored.

Enable live trading (optional)

Only do this if you acknowledge that every order is a real order. There is no sandbox, no paper account, no ability to undo.

1. Set WEBULL_ENABLE_TRADING=true in the .env; the value must be exactly true.

2. Restart your MCP client. The trading tools are registered at import time, so a restart is mandatory.

3. Use the trading_status tool to verify.

Now, there are still two independent safety layers:

• Registration gate — if the flag is not set or is false, place_order, preview_order, and cancel_order are never exposed to the model. The model cannot call a tool it cannot see.

• Confirmation gate — even when enabled, place_order will fail unless called with confirm=True. Always run `preview_order first.

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

Instructions on notes and limitations

• Region defaults to us. Use WE_BULL_REGION for other markets.

• Order tool supports stocks only — options trading is not implemented. This option support is only market data.

• Webull does not provide an option-chain endpoint for query. Create your own OCC symbols. Contract symbols that have expired will return INVALID_SYMBOL.

• Intended for a unified, symbol-based webull-openapi-python-sdk. The old, split webull-python-sdk-* packages use a different instrument ID based API — do not install both.

• SDK will write any logs under logs/. These logs contain your App Key, 2FA token, and account IDs. They are gitignored, and before attaching to bug report, be sure to redact them.

Contributing

See CONTRIBUTING.md. Bug reports are welcome.

Licence

MIT.