Webull MCP Server

Un servidor MCP que expone la OpenAPI oficial de Webull (webull-openapi-python-sdk) como herramientas que un cliente MCP — Claude Code, Clade Desktop, o cualquier otro — puede llamar. Lee saloes de cuenta, posiciones, órdenes, cotizaciones de acciones, velas históricas y datos de mercado de opciones estadounidenses; consulta, opcionalmente, colocar y cancelar órdenes de acciones reales.

⚠️ Lee esto antes de instalar

No not official. Este proyecto no está afiliado, respaldado ni apoyado por Webull. He goes to Webull's OpenAPI as a client of third parties, and Nota: La API poguè camiar o deimportant sin aviso; nada aquí goes guaranteed.

No es financial advice. Esto es una tubería, not a strategy. No tiene no no opinion about what to buy or sell. Eres el único responsable de cada orden that leaves your account and every dollar it costs you.

Trading está deshabilitado por defecto — and no hay mode "paper". And las order tools no even are registered with the MCP client unless you establezcas WEBULL_ENABLE_TRADING=true. Webull no publica ningún endpoint de paper -trading, and so, una vez habilitado, each order this server places is live, con dinero real, en una cuenta real. Vee Habilitar el trading en vivo.

Your credentials will be on your machine. Your App Key and Secret live only on a .env local file, which is gitignote. Solo se sending to Webull's API — never al model, never to any third party.

Herramientas

De solo lectura (siempre disponible)

Las options tools use OCC format (AAPL260619C003000 — <ROOT><YYMDD><C|P><strike × 1000, 8 dítgits>). Webull no tiene endpoint de cotización de cadena r, así que build candidate symbols you aself.

Trading en vivo (gated, off por defecto)

Registered only when WEBULL_ENABLE_TRADING=true:

Compatible orderes, accepted: MARKET, LIT, STOP_LOSS, STOP_LOSS_LIT; DAY or GTC; optional extended-hours xouting.

Ejemplo de session

Lo que que se actually looks like from an MCP client. Los valors below are ilustrative — subtituye tu 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.

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

Instalación

1. Obtenga Webull API credentials

1. Ir to Webull Developer port and in your a Webull account that you want the server to have.

2. Apá for OpenAPI and create an app. Approvación is not instantaneous — Webull reviews the request.

3. Copíe the App Key and App Secret generated.

Your account must have OpenAPI habilitado for your region. La real-time market data to a market-data entitlement"en tu cuenta; con without of it, quotes may be delayed.

2. Instalación

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

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

Prescibe PiPthon 3.10 or newer.

3. Configuración

cp .env.example .env

Ed .env and fill your credenciales:

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, never past any of its contents.

4. Regístrese with your MCP client

Ed .mcp.json and reemplace the "path" placeholders with an absolute path a tu clone:

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

Por Claude, Code, both create .mcp.json in a projectc directory, where se detectionauto, or regístrelo explícit:

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

Reinicia tu client. Verify that el server arranque:

.venv/bin/python src/server.py

Debe arranc and wait on stdio — not output is correct. Ctrl-C for exit.

On the first call that touches your account, the SDK does a 2FA handshake and cache a token under conf/. That directory is. No te commits.

Enable live trading (optional)

Real only if you accept that every order is real. There is not sandbox, no "paper" account, no reverse.

1. Set WEB_MULL_ENABLE_TRADING=true in .env — the string must be exactly true.

2. Reinicia tu client. The trading tools are registered at "import time", your reinicia required.

3. Confirm the trading_status tool.

There are still two capas of safety:

• Registro gate — with the key unset or false, place_order, preview_order, and cancel_order are never seen by the model. He cannot call a tool it cannot see.

• Confirmación gate — even if enabled, place_order lanza error except if called with confirm=True. Run preeview_order firsta.

Para disable again, put the flag at false and reinici.

Notes and limitaciones

• La region default is us. Set WEB_PULL_REGION for other markets.

• Order tools cover only actions only — opciónes trading no está implemented. The option support here is only market data.

• Webull no expose an endpoint which lists the option chain. Building OCC symbols yourself. Expired contracts return INVALID_SYMBOL, and Friday's expirations shift to Thursday in case Friday is market holiiday.

• Built on toe new unified symbol-based webull-openapi-python-sdk. The old separate webull-python-sdk-* packages use a different instrument-id-basado API — no inc all

• The SDK writes logs in logs/. these logs contain your App Key, your 2FA token and your acount IDs. They are in gitignore; never do attach one to a bug report without removing data first.

Contributions

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

License

MIT.