Webull Local MCP Server

Webull Local 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 Local MCP

Webull Local 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 and historical market data (stocks, options, futures, crypto, event contracts)
Look up instruments, fundamentals, financial statements, and institution/insider data
Search market news, use screeners, and manage watchlists
Browse and publish community posts and comments
View account balances and positions
Place, preview, 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
`add_watchlist_instruments`	Add instruments to a watchlist.
`cancel_order`	Cancel an unfilled order (stocks, options, futures, crypto, event contracts).
`create_community_comment`	Create a plain-text comment on a community post (write operation, publishes under your account; US only).
`create_community_post`	Create a plain-text community post, optionally tagged with a symbol (write operation, publishes under your account; US only).
`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_community_hot_stocks`	List stocks ranked by community activity (US only).
`get_community_post_detail`	Get detailed information for a community post, including attached tickers (US only).
`get_community_posts`	List community posts for a symbol, with optional keyword search and pagination (US only).
`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_insider_holdings`	Get insider ownership statistics overview for a US stock.
`get_insider_transactions`	Get insider transaction records for a US stock (optional BUY/SELL filter).
`get_institution_holding_changes`	Get a US institution's holding changes by position type (OPEN/CLOSE/CHANGE).
`get_institution_holdings`	Get a US institution's 13F holdings.
`get_institution_identifier`	Search US institutional investors by name or SEC CIK.
`get_instruments`	Get stock/ETF instrument info.
`get_macroeconomic_calendar`	Get the US macroeconomic event calendar for a date range.
`get_market_sectors`	Get market sector overview ranking.
`get_market_sectors_detail`	Get stock list and statistics for a specific market sector.
`get_market_sentiment`	Get the US market fear & greed sentiment index with historical comparison points.
`get_most_active`	Get most actively traded stocks ranking.
`get_my_community_posts`	List community posts created by the current user (US only).
`get_news_detail`	Get the full content of a US market news article by ID.
`get_open_orders`	Get all current open/pending orders.
`get_option_bars`	Get option historical OHLCV bars (batch). Requires option market data subscription.
`get_option_contracts`	List US-listed option contracts by underlying, expiry, strike, type, etc.
`get_option_snapshot`	Get real-time option snapshots (up to 20 symbols). Requires option market data subscription.
`get_option_tick`	Get option tick-by-tick trade data for a contract. Requires option market data subscription.
`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_footprint`	Get stock large order footprint (order flow).
`get_stock_forecast_eps`	Get forecast EPS for a stock.
`get_stock_industry_comparison`	Get industry comparison for a stock (up to 20 peers).
`get_stock_news`	Get news related to a US stock, with optional sentiment filter.
`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_stock_unusual_activities`	Get recent unusual activity alerts (volume surge, price spike) for US stocks.
`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_futures_order`	Preview a futures order without submitting (estimated costs and margin).
`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.
`search_news`	Search US market news by keyword.
`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`	`us`	`us`
`WEBULL_TOOLSETS`	Enabled tool categories (comma-separated). Valid values: `account`, `instrument`, `market-data`, `trading`	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_TOKEN_DIR`	Token storage directory	`./conf/`
`WEBULL_AUDIT_LOG_FILE`	Audit log file path	stderr only
`WEBULL_LOG_LEVEL`	SDK log level	`WARNING`

For read-only access, set WEBULL_TOOLSETS=account,instrument,market-data to disable trading tools. The instrument toolset includes instruments, fundamentals, financial statements, and institution/insider data; omit it if you don't need them. Note that market-data includes watchlist and community write 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 / preview_futures_order before placing orders.
create_community_post and create_community_comment publish content under your account. Review the text before confirming.
Use WEBULL_SYMBOL_WHITELIST to restrict tradable symbols.

Disclosure

Webull Local 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 Local 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​