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

Apply based on your account type:

Individual users: Trading API Application Guide

Institutional users: Broker API Application Guide

Sandbox (Test)

No application required. Use the publicly shared test credentials to get started immediately. See SDKs and Tools.

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

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"
      }
    }
  }
}

Cursor

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"
      }
    }
  }
}

Claude Desktop

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
get_account_list	Get all linked accounts
get_account_balance	Get account balance, buying power, and cash details
get_account_positions	Get current positions and holdings
get_stock_tick	Get stock tick-by-tick trade data
get_stock_snapshot	Get real-time stock snapshot (HK, US, A-share)
get_stock_quotes	Get real-time bid/ask quotes with depth
get_stock_footprint	Get stock large order footprint (order flow)
get_stock_bars	Get stock OHLCV bars in batch
get_stock_bars_single	Get OHLCV bars for a single stock
get_instruments	Get stock instrument info
place_stock_order	Place a stock order
preview_stock_order	Preview a stock order without submitting
replace_stock_order	Modify an existing stock order
place_option_single_order	Place a single-leg option order
preview_option_order	Preview an option order without submitting
replace_option_order	Modify an existing option order
cancel_order	Cancel an unfilled order
get_order_history	Get historical orders
get_open_orders	Get all current open/pending orders
get_order_detail	Get single order details

---

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.

---

Related Links

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