Webull OpenAPI MCP Server

MCP Server for Webull OpenAPI — enables AI assistants (Cursor, Claude Desktop, Kiro, etc.) to securely access Webull trading and market data.

⚠️ Disclaimer

The information provided by this tool is for reference only and does not constitute investment advice. Trading involves risk; please make decisions carefully.

See DISCLAIMER.md for the full disclaimer.

Features

• Multi-Region Support — US, HK, JP, SG, TH, MY, UK, MX, BR, EU, ZA, and AU regions with region-specific order types, trading sessions, and validation
• Market Data — Real-time snapshots, tick data, quotes (depth), footprint, and OHLCV bars for stocks, options, futures, crypto, and event contracts
• NOII Data — Net Order Imbalance Indicator bars and snapshots for US stock opening/closing auctions
• Screener — Top gainers/losers, most active, market sectors, high dividend, and 52-week high/low rankings
• Watchlist — Create, manage, and query user watchlists and instruments
• Fundamental Data — Company profiles, analyst ratings, and target prices
• Stock & Fund Fundamentals — Capital flow, SEC filings, earnings/dividend calendar, forecast EPS, industry comparison, and full fund data (rating, performance, allocation, holdings, brief, dividends, splits, net value, files)
• Financial Statements — Financial alert, indicators, income statement, balance sheet, and cash flow
• Trading — Place, modify, cancel orders for stocks, options, futures, crypto, and event contracts
• Combo Orders — OTO, OCO, OTOCO combo orders (US only)
• Option Strategies — Multi-leg option strategies: vertical, straddle, strangle, butterfly, condor, etc. (US only)
• Algo Orders — TWAP, VWAP, POV algorithmic orders (US only)
• Risk Controls — Market-specific notional limits (USD/HKD/CNH/JPY), quantity limits, symbol whitelist
• Auto Account Resolution — Automatically selects the correct account based on asset type (stock, futures, crypto, event)
• Audit Logging — All order operations are logged for compliance
• 2FA Support — Interactive authentication flow for accounts with Two-Factor Authentication

Example Prompts

Here are some prompts you can use with your AI assistant:

Market Data

• Show me AAPL's daily bars for the last 5 days
• Get a real-time snapshot for AAPL, MSFT, and GOOGL
• What's the current bid/ask for TSLA?
• Show me 1-minute tick data for NVDA
• Show me the NOII data for AAPL before market open

Screener

• What are today's top gainers?
• Show me the biggest losers in pre-market
• What are the most actively traded stocks right now?
• Show me the market sectors overview
• List high dividend stocks
• Which stocks are making new 52-week highs?

Watchlist

• Show me all my watchlists
• Create a new watchlist called "Tech Stocks"
• Add AAPL and MSFT to my watchlist
• What stocks are in my watchlist?

Fundamental & Analyst

• Tell me about NVDA's company profile
• What do analysts rate AAPL?
• What's the analyst target price for TSLA?
• Show me the capital flow for AAPL
• Get TSLA's earnings calendar
• Show NVDA's industry comparison
• What are QQQ's top holdings and fund performance?

Financial Statements

• Show me AAPL's latest income statement
• Get TSLA's balance sheet for the last 4 quarters
• What's NVDA's cash flow statement?
• Show me the financial indicators for MSFT

Account & Portfolio

• What's my account balance and buying power?
• Show me all my current positions
• List all my linked accounts

Stock Trading

• Place a limit order to buy 100 shares of AAPL at $250
• Place a market order to sell 50 shares of TSLA
• Preview a limit buy order for 200 shares of MSFT at $450 before placing it

Options Trading

• Buy 1 AAPL call option, strike $250, expiring 2026-04-17, limit price $5.00
• Buy 1 TSLA put option, strike $200, expiring 2026-05-15

Option Market Data

• Get a snapshot for AAPL260522C00300000
• Show me tick data for TSLA251219C00450000
• Get daily bars for AAPL260522C00300000
• List available option contracts for AAPL expiring after 2026-06-01

Order Management

• Show me my order history for the last 7 days
• What are my current open orders?
• Cancel order with ID abc123

HK Market

• Place an enhanced limit order to buy 100 shares of Tencent (00700) at HKD 500
• Place an at-auction limit order for 200 shares of 00700 at HKD 510

Prerequisites

1. Webull Developer Account — Register at:
   • US: developer.webull.com
   • HK: developer.webull.hk
   • JP: developer.webull.co.jp
   • SG: developer.webull.com.sg
   • TH: developer.webull.co.th
   • MY: developer.webull.com.my
   • UK: developer.webull-uk.com
   • EU: developer.webull.eu
   • ZA: developer.webull.co.za
   • AU: developer.webull.com.au
   • MX: developer.webull.com.mx
   • BR: developer.webull.com.br
2. API Credentials — Obtain your App Key and App Secret
3. Market Data Subscription — Subscribe to quotes for market data access:
   • US: webullapp.com/quote | Guide
   • HK: webullapp.hk/quote | Guide
   • JP: webull.co.jp/pricing | Guide
   • SG: webull.com.sg/quote | Guide
   • TH: webull.co.th/quote | Guide
   • MY: webull.com.my/quote | Guide
   • UK: webull-uk.com/quote | Guide
   • EU: webullapp.eu/quote | Guide
   • ZA: webullapp.co.za/quote | Guide
   • AU: webullapp.com.au/quote | Guide
   • MX: webull.com.mx/quote | Guide
   • BR: webull.com.br/quote | Guide
4. Python 3.10+
5. uv (recommended) — Install guide

Quick Start

Step 1: Configure Credentials

Before running the server, you must configure your API credentials. Choose one of the following approaches:

Option A: MCP client configuration (recommended for production)

Add credentials via the env field in your MCP client config (Kiro, Cursor, Claude Desktop, etc.):

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

Option B: .env file

# Create a .env file interactively:
uvx webull-openapi-mcp init

# Or manually create .env with:
# WEBULL_APP_KEY=your_app_key
# WEBULL_APP_SECRET=your_app_secret

Step 2: Authenticate (2FA)

If your account requires Two-Factor Authentication, run the auth command and approve in your Webull mobile app:

uvx webull-openapi-mcp auth

Token is valid for 15 days and auto-refreshes. You only need to do this once (or when the token expires).

Step 3: Start the Server

uvx webull-openapi-mcp serve

That's it. Your AI assistant can now access Webull trading and market data.

Installation Options

Option 1: uvx (Recommended)

No installation needed. uvx downloads and runs the package directly from PyPI:

uvx webull-openapi-mcp serve

Option 2: pip

pip install webull-openapi-mcp
webull-openapi-mcp serve

Option 3: Local Development

git clone https://github.com/webull-inc/webull-openapi-mcp.git
cd webull-openapi-mcp
uv sync
uv run python -m webull_openapi_mcp serve

Client Configuration

Kiro / Cursor / Claude Desktop / Claude Code

Add to your MCP configuration:

Using environment variables:

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