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
Sandbox (Test)

Apply based on your account type:

Individual users: Individual Application Guide

Institutional users: Institution Application Guide

Other Requirements

Market Data Subscription (if market data is needed): webullapp.com/quote | 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
Claude Desktop
Kiro

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

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

tip

For sandbox environment, set WEBULL_ENVIRONMENT to uat.

Step 3: Authenticate

note

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

Trading

Buy 100 shares of AAPL at market price

Buy 10 shares of TSLA 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/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_futures_tick`	Get futures tick-by-tick trade data
`get_futures_snapshot`	Get futures real-time snapshot
`get_futures_depth`	Get futures order book depth
`get_futures_bars`	Get futures OHLCV bars
`get_futures_footprint`	Get futures large order footprint
`get_crypto_snapshot`	Get cryptocurrency real-time snapshot
`get_crypto_bars`	Get cryptocurrency OHLCV bars
`get_event_tick`	Get event contract tick-by-tick data
`get_event_snapshot`	Get event contract real-time snapshot
`get_event_depth`	Get event contract order book depth
`get_event_bars`	Get event contract OHLCV bars
`get_instruments`	Get stock/ETF instrument info
`get_futures_instruments`	Get futures instrument info
`get_futures_instruments_by_code`	Get futures contracts by product code
`get_futures_products`	Get all futures products and codes
`get_crypto_instruments`	Get cryptocurrency instrument info
`get_event_series`	Get event contract series
`get_event_instruments`	Get event contract instruments by series
`get_event_categories`	Get event contract categories
`get_event_events`	Get events within a series
`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_stock_combo_order`	Place a combo stock order (OTO/OCO/OTOCO)
`place_algo_order`	Place an algorithmic order (TWAP/VWAP/POV)
`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
`place_option_strategy_order`	Place a multi-leg option strategy order
`place_futures_order`	Place a futures order
`replace_futures_order`	Modify an existing futures order
`place_crypto_order`	Place a cryptocurrency order
`place_event_order`	Place an event contract order
`replace_event_order`	Modify an existing event contract 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`	`us`	`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

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, cryptocurrencies, 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.com
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​

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​