webull-openapi-mcp

<!-- mcp-name: io.github.webull-inc/webull-openapi-mcp -->

# Webull OpenAPI MCP Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)

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](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, 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) (US/HK/JP only)
- **Financial Statements** — Financial alert, indicators, income statement, balance sheet, and cash flow (US/HK/JP only)
- **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

**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](https://developer.webull.com/apis/home)
   - HK: [developer.webull.hk](https://developer.webull.hk/apis/home)
   - JP: [developer.webull.co.jp](https://developer.webull.co.jp/)
   - SG: [developer.webull.com.sg](https://developer.webull.com.sg/apis/home)
   - TH: [developer.webull.co.th](https://developer.webull.co.th/apis/home)
   - MY: [developer.webull.com.my](https://developer.webull.com.my/apis/home)
   - UK: [developer.webull-uk.com](https://developer.webull-uk.com/apis/home)
   - EU: [developer.webull.eu](https://developer.webull.eu/apis/home)
   - ZA: [developer.webull.co.za](https://developer.webull.co.za/apis/home)
   - AU: [developer.webull.com.au](https://developer.webull.com.au/apis/home)
   - MX: [developer.webull.com.mx](https://developer.webull.com.mx/apis/home)
   - BR: [developer.webull.com.br](https://developer.webull.com.br/apis/home)
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](https://www.webullapp.com/quote) | [Guide](https://developer.webull.com/apis/docs/market-data-api/subscribe-quotes)
   - HK: [webullapp.hk/quote](https://www.webullapp.hk/quote) | [Guide](https://developer.webull.hk/apis/docs/market-data-api/subscribe-quotes)
   - JP: [webull.co.jp/pricing](https://www.webull.co.jp/pricing) | [Guide](https://developer.webull.co.jp/api-doc/market-data/subscribe-quotes/)
   - SG: [webull.com.sg/quote](https://www.webull.com.sg/quote) | [Guide](https://developer.webull.com.sg/apis/docs/market-data-api/subscribe-quotes)
   - TH: [webull.co.th/quote](https://www.webull.co.th/quote) | [Guide](https://developer.webull.co.th/apis/docs/market-data-api/subscribe-quotes)
   - MY: [webull.com.my/quote](https://www.webull.com.my/quote) | [Guide](https://developer.webull.com.my/apis/docs/market-data-api/subscribe-quotes)
   - UK: [webull-uk.com/quote](https://www.webull-uk.com/quote) | [Guide](https://developer.webull-uk.com/apis/docs/market-data-api/subscribe-quotes)
   - EU: [webullapp.eu/quote](https://www.webullapp.eu/quote) | [Guide](https://developer.webull.eu/apis/docs/market-data-api/subscribe-quotes)
   - ZA: [webullapp.co.za/quote](https://www.webullapp.co.za/quote) | [Guide](https://developer.webull.co.za/apis/docs/market-data-api/subscribe-quotes)
   - AU: [webullapp.com.au/quote](https://www.webullapp.com.au/quote) | [Guide](https://developer.webull.com.au/apis/docs/market-data-api/subscribe-quotes)
   - MX: [webull.com.mx/quote](https://www.webull.com.mx/quote) | [Guide](https://developer.webull.com.mx/apis/docs/market-data-api/subscribe-quotes)
   - BR: [webull.com.br/quote](https://www.webull.com.br/quote) | [Guide](https://developer.webull.com.br/apis/docs/market-data-api/subscribe-quotes)
4. **Python 3.10+**
5. **uv** (recommended) — [Install guide](https://docs.astral.sh/uv/getting-started/installation/)

---

## 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.):

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

**Option B: .env file**

```bash
# 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:

```bash
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

```bash
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:

```bash
uvx webull-openapi-mcp serve
```

### Option 2: pip

```bash
pip install webull-openapi-mcp
webull-openapi-mcp serve
```

### Option 3: Local Development

```bash
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:**

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

**Using .env file (local development):**

```json
{
  "mcpServers": {
    "webull": {
      "command": "uv",
      "args": [
        "run", "--directory", "/path/to/webull-openapi-mcp",
        "python", "-m", "webull_openapi_mcp",