Webull MCP Server

Webull MCP Server enables AI assistants (Kiro, Cursor, Claude Desktop, etc.) to securely access Webull OpenAPI trading and market data capabilities via the Model Context Protocol (MCP).

Source code: webull-inc/webull-mcp-servers

What is Webull MCP

Webull MCP Server is a server built on the Model Context Protocol that wraps Webull OpenAPI capabilities into tools callable by AI assistants. With MCP, you can use natural language in your AI coding assistant to:

Query real-time market data (HK stocks, US stocks, China A-shares)
View account balances and positions
Place, modify, and cancel orders (stocks, options)
Query order history and order details

The HK region supports Hong Kong, US, and China A-share markets, automatically adapting to region-specific order types (Enhanced Limit, At-Auction, At-Auction Limit, etc.), trading sessions, and validation rules.

Architecture Overview

Prerequisites

API Credentials (App Key and App Secret)

Production
Sandbox (Test)

Apply based on your account type:

Individual users: Trading API Application Guide

Institutional users: Broker API Application Guide

Other Requirements

Market Data Subscription (if market data is needed): webullapp.hk/quote | Subscription Guide
uvx (Python 3.10+ required) — uv Installation Guide
MCP-compatible AI Client — e.g. Kiro, Cursor, Claude Desktop

Demo Video

Setup Steps

Step 1: Install

Ensure Python 3.10+ and uvx are installed. No need to manually install Webull MCP Server — your AI client will automatically download and launch it via uvx.

Step 2: Configure AI Client

Add the following configuration to your AI client's MCP config file. Replace your_app_key and your_app_secret with the credentials obtained in the prerequisites:

Kiro
Cursor
Claude Desktop

Edit .kiro/settings/mcp.json:

{
  "mcpServers": {
    "webull": {
      "command": "uvx",
      "args": ["webull-openapi-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_app_key",
        "WEBULL_APP_SECRET": "your_app_secret",
        "WEBULL_REGION_ID": "hk",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

Edit .cursor/mcp.json:

{
  "mcpServers": {
    "webull": {
      "command": "uvx",
      "args": ["webull-openapi-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_app_key",
        "WEBULL_APP_SECRET": "your_app_secret",
        "WEBULL_REGION_ID": "hk",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "webull": {
      "command": "uvx",
      "args": ["webull-openapi-mcp", "serve"],
      "env": {
        "WEBULL_APP_KEY": "your_app_key",
        "WEBULL_APP_SECRET": "your_app_secret",
        "WEBULL_REGION_ID": "hk",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

tip

For sandbox environment, set WEBULL_ENVIRONMENT to uat.

Step 3: Authenticate

Complete a one-time authentication in the terminal before first use:

uvx webull-openapi-mcp auth

Authentication flow:

After approving the request in the Webull App, the token is saved locally. The token is valid for 15 days and auto-refreshes on use.

Step 4: Verify Connection

Restart your AI client and try the following in a conversation:

Get my account list

If your account information is returned, Webull MCP is successfully connected.

Usage Examples

Market Data

Get a real-time snapshot for 00700

Show me AAPL's daily bars for the last 5 days

Trading

Buy 100 shares of Tencent (00700) at market price

Buy 10 shares of AAPL at market price

Available Endpoints

Endpoint	Description
`add_watchlist_instruments`	Add instruments to a watchlist.
`cancel_order`	Cancel an unfilled order (stocks, options, futures, crypto, event contracts).
`create_watchlist`	Create a new watchlist.
`delete_watchlist`	Delete a watchlist and all its instruments (irreversible).
`get_52_week_high_low`	Get 52-week high/low stocks ranking.
`get_account_balance`	Get account balance (net liquidation, buying power, cash, market value, P&L).
`get_account_list`	Get all linked accounts.
`get_account_positions`	Get account positions list.
`get_analyst_rating`	Get analyst rating for a security (strong buy/buy/hold/sell counts).
`get_analyst_target_price`	Get analyst consensus target price for a security.
`get_balance_sheet`	Get balance sheet for a stock across periods.
`get_cash_flow`	Get cash flow statement for a stock across periods.
`get_company_profile`	Get company profile (business description, industry, CEO, employees, etc.).
`get_crypto_bars`	Get cryptocurrency OHLCV bars.
`get_crypto_instruments`	Get cryptocurrency instrument info.
`get_crypto_snapshot`	Get cryptocurrency real-time snapshot.
`get_event_bars`	Get event contract OHLCV bars.
`get_event_categories`	Get event contract category list.
`get_event_depth`	Get event contract order book depth.
`get_event_events`	Get events within a series.
`get_event_instruments`	Get event contract instruments by series.
`get_event_series`	Get event contract series (recurring event templates).
`get_event_snapshot`	Get event contract real-time snapshot.
`get_event_tick`	Get event contract tick-by-tick trade data.
`get_financial_alert`	Get financial alert (next report estimates vs last year).
`get_financial_indicators`	Get financial indicators (key ratios/metrics) for a stock.
`get_fund_allocation`	Get fund asset allocation by date.
`get_fund_brief`	Get fund brief information.
`get_fund_dividends`	Get fund dividend history.
`get_fund_files`	Get fund files/documents.
`get_fund_holdings`	Get fund top 10 holdings.
`get_fund_net_value`	Get fund net value (NAV) history.
`get_fund_performance`	Get fund performance returns over multiple horizons.
`get_fund_rating`	Get fund rating history.
`get_fund_splits`	Get fund split history.
`get_futures_bars`	Get futures OHLCV bars in batch.
`get_futures_depth`	Get futures order book depth.
`get_futures_footprint`	Get futures large order footprint (order flow).
`get_futures_instruments`	Get futures instrument info.
`get_futures_product_class`	Get all futures product classification groups.
`get_futures_products`	Get all futures products and product codes.
`get_futures_snapshot`	Get futures real-time snapshot.
`get_futures_tick`	Get futures tick-by-tick trade data.
`get_gainers_losers`	Get top gainers or losers ranking by price change.
`get_high_dividend`	Get high dividend stocks ranking.
`get_income_statement`	Get income statement for a stock across periods.
`get_instruments`	Get stock/ETF instrument info.
`get_market_sectors`	Get market sector overview ranking.
`get_market_sectors_detail`	Get stock list and statistics for a specific market sector.
`get_most_active`	Get most actively traded stocks ranking.
`get_open_orders`	Get all current open/pending orders.
`get_order_detail`	Get single order details.
`get_order_history`	Get historical orders (default last 7 days).
`get_stock_bars`	Get stock OHLCV bars in batch (multiple symbols).
`get_stock_bars_single`	Get OHLCV bars for a single stock.
`get_stock_capital_flow`	Get capital flow distribution for a stock by date.
`get_stock_dividend_calendar`	Get dividend calendar for a stock.
`get_stock_earnings_calendar`	Get earnings calendar for a stock.
`get_stock_filings`	Get SEC filings for a US stock (last 3 years).
`get_stock_forecast_eps`	Get forecast EPS for a stock.
`get_stock_footprint`	Get stock large order footprint (order flow).
`get_stock_industry_comparison`	Get industry comparison for a stock (up to 20 peers).
`get_stock_noii_bars`	Get NOII K-line data for a stock (opening/closing auction imbalance).
`get_stock_noii_snapshot`	Get latest NOII snapshot for a stock during auction phases.
`get_stock_quotes`	Get real-time stock bid/ask quotes with depth.
`get_stock_snapshot`	Get real-time stock/ETF snapshot (supports multiple symbols).
`get_stock_tick`	Get stock tick-by-tick trade data.
`get_watchlist_instruments`	Get all instruments in a watchlist.
`get_watchlists`	Get all watchlists for the current user.
`place_algo_order`	Place an algorithmic order (TWAP, VWAP, POV).
`place_crypto_order`	Place a cryptocurrency order.
`place_event_order`	Place an event contract order.
`place_futures_order`	Place a futures order.
`place_option_single_order`	Place a single-leg option order.
`place_option_strategy_order`	Place a multi-leg option strategy order.
`place_stock_combo_order`	Place a combo stock order (OTO/OCO/OTOCO).
`place_stock_order`	Place a stock order (single, non-combo).
`preview_option_order`	Preview an option order without submitting.
`preview_stock_order`	Preview a stock order without submitting.
`remove_watchlist_instruments`	Remove instruments from a watchlist.
`replace_event_order`	Modify an existing event contract order.
`replace_futures_order`	Modify an existing futures order.
`replace_option_order`	Modify an existing option order.
`replace_stock_order`	Modify an existing stock order.
`update_watchlist`	Update an existing watchlist's name or sort order.
`update_watchlist_instruments`	Update the sort order of instruments in a watchlist.

Configuration Parameters

Variable	Description	Default
`WEBULL_APP_KEY`	App Key (required)	—
`WEBULL_APP_SECRET`	App Secret (required)	—
`WEBULL_ENVIRONMENT`	`uat` (sandbox) or `prod` (production)	`uat`
`WEBULL_REGION_ID`	Set to `hk`	`us`
`WEBULL_TOOLSETS`	Enabled tool categories (comma-separated)	all enabled
`WEBULL_MAX_ORDER_NOTIONAL_USD`	Max order notional for US market (USD)	`10000`
`WEBULL_MAX_ORDER_NOTIONAL_HKD`	Max order notional for HK market (HKD)	`80000`
`WEBULL_MAX_ORDER_NOTIONAL_CNH`	Max order notional for A-share market (CNH)	`70000`
`WEBULL_MAX_ORDER_QUANTITY`	Max order quantity per order	`1000`
`WEBULL_SYMBOL_WHITELIST`	Allowed symbols whitelist (comma-separated)	no restriction

For read-only access (market data + account only), set WEBULL_TOOLSETS=account,market-data to disable trading tools.

Security Recommendations

Never share your App Key, App Secret, or Token via chat with an AI model. These credentials should only be passed to the MCP Server process via the env field in mcp.json, never as conversation content.
Use preview_stock_order / preview_option_order before placing orders.
Use WEBULL_SYMBOL_WHITELIST to restrict tradable symbols.

Disclosure

Webull MCP Server provides information solely for reference purposes and does not constitute investment advice. Trading in securities, options, and other financial instruments involves substantial risk of loss. All trading decisions are made at your own discretion and risk. You are solely responsible for verifying order details before execution. This software is provided "as is" without warranty of any kind.

Webull OpenAPI Docs: developer.webull.hk
MCP Protocol: modelcontextprotocol.io
Python SDK: pip install webull-openapi-python-sdk

What is Webull MCP​

Architecture Overview​

Prerequisites​

API Credentials (App Key and App Secret)​

Other Requirements​

Demo Video​

Setup Steps​

Step 1: Install​

Step 2: Configure AI Client​

Step 3: Authenticate​

Step 4: Verify Connection​

Usage Examples​

Market Data​

Trading​

Available Endpoints​

Configuration Parameters​

Security Recommendations​

Disclosure​

Related Links​