Webull MCP Server

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

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

---

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
• View account balances and positions
• Place, modify, and cancel orders
• Query order history and order details

Architecture Overview

---

Prerequisites

API Credentials (App Key and App Secret)

Production

Apply at: Individual Application Guide

UAT (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): Subscription Guide
• uvx (Python 3.10+ required) — uv Installation Guide
• MCP-compatible AI Client — e.g. Cursor, Claude Desktop, Kiro

---

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:

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": "sg",
        "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": "sg",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

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": "sg",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

Tip: For uat environment, set WEBULL_ENVIRONMENT to uat.

Step 3: Authenticate

This step is only required if your account has Two-Factor Authentication enabled.

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 AAPL

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

What are today's top gainers in the US market?

Trading

Buy 100 shares of AAPL at limit price $200

Place a market order to sell 50 shares of TSLA

Show my open orders

---

Available Endpoints

The SG region supports US stock and ETF trading. The following tools are available:

Account

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

Instrument

Endpoint	Description
get_instruments	Get stock/ETF instrument info (US_STOCK, US_ETF only)
get_company_profile	Get company profile including business description, industry, sector
get_analyst_rating	Get analyst rating for a security
get_analyst_target_price	Get analyst target price for a security

Market Data

Endpoint	Description
get_stock_tick	Get stock tick-by-tick trade data
get_stock_snapshot	Get real-time stock/ETF snapshot
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_stock_noii_bars	Get NOII (Net Order Imbalance Indicator) OHLCV bars for a stock
get_stock_noii_snapshot	Get latest NOII snapshot for a stock during auction phases
get_gainers_losers	Get top gainers or losers ranking by price change
get_most_active	Get most actively traded stocks ranking
get_watchlists	Get all watchlists for the current user
create_watchlist	Create a new watchlist
update_watchlist	Update an existing watchlist's name or sort order
delete_watchlist	Delete a watchlist and all instruments in it
get_watchlist_instruments	Get all instruments in a watchlist
add_watchlist_instruments	Add instruments to a watchlist
remove_watchlist_instruments	Remove instruments from a watchlist
update_watchlist_instruments	Update the sort order of instruments in a watchlist

Trading

Endpoint	Description
place_stock_order	Place a stock order
preview_stock_order	Preview a stock order without submitting
replace_stock_order	Modify an existing stock 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 or prod (production)	uat
WEBULL_REGION_ID	Set to sg	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_QUANTITY	Max order quantity per order	1000
WEBULL_SYMBOL_WHITELIST	Allowed symbols whitelist (comma-separated)	no restriction
WEBULL_AUDIT_LOG_FILE	Path to audit log file	disabled

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 before placing orders to verify estimated costs.
• Use WEBULL_SYMBOL_WHITELIST to restrict tradable symbols.
• Use WEBULL_MAX_ORDER_NOTIONAL_USD and WEBULL_MAX_ORDER_QUANTITY to set per-order risk limits.

---

Disclosure

Webull MCP Server provides information solely for reference purposes and does not constitute investment advice. Trading in securities 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

• MCP Protocol: modelcontextprotocol.io
• Python SDK: pip install webull-openapi-python-sdk
• Source Code: webull-inc/webull-openapi-mcp