⚠️ DEPRECATED — This project is no longer maintained

This repository has been deprecated and will be archived soon.

All development has moved to the new repository: webull-openapi-mcp

Please migrate to the new project for continued support, bug fixes, and new features. No further updates will be made to this repository.

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 and HK 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
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), 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

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

Webull Developer Account — Register at:
- US: developer.webull.com
- HK: developer.webull.hk
API Credentials — Obtain your App Key and App Secret
Market Data Subscription — Subscribe to quotes for market data access:
- US: webullapp.com/quote | Guide
- HK: webullapp.hk/quote | Guide
Python 3.10+
uv (recommended) — Install guide

Installation

Option 1: uvx (Recommended)

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-mcp-server.git
cd webull-mcp-server
uv sync
uv run python -m webull_openapi_mcp serve

Quick Start

1. Initialize Configuration

webull-openapi-mcp init

Creates a .env file. Fill in your WEBULL_APP_KEY and WEBULL_APP_SECRET.

2. Authenticate

webull-openapi-mcp auth

For 2FA accounts: approve the request in your Webull mobile app. Token is valid for 15 days and auto-refreshes.

3. Start the Server

webull-openapi-mcp serve

Client Configuration

Kiro / Cursor / Claude Desktop

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

Using .env file (local development):

{
  "mcpServers": {
    "webull": {
      "command": "uv",
      "args": [
        "run", "--directory", "/path/to/webull-mcp-server",
        "python", "-m", "webull_openapi_mcp", "serve",
        "--env-file", "/path/to/.env"
      ]
    }
  }
}

Configuration

Variable	Description	Default
`WEBULL_APP_KEY`	App Key (required)	—
`WEBULL_APP_SECRET`	App Secret (required)	—
`WEBULL_ENVIRONMENT`	`uat` (sandbox) or `prod`	`uat`
`WEBULL_REGION_ID`	`us` or `hk`	`us`
`WEBULL_TOOLSETS`	Enabled tool categories (comma-separated)	(all enabled)
`WEBULL_MAX_ORDER_NOTIONAL_USD`	Max order value for US market (USD)	`10000`
`WEBULL_MAX_ORDER_NOTIONAL_HKD`	Max order value for HK market (HKD)	`80000`
`WEBULL_MAX_ORDER_NOTIONAL_CNH`	Max order value for CN market (CNH)	`70000`
`WEBULL_MAX_ORDER_QUANTITY`	Max order quantity	`1000`
`WEBULL_SYMBOL_WHITELIST`	Allowed symbols (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`

Note: WEBULL_REGION_ID=us represents Webull US (developer.webull.com), and WEBULL_REGION_ID=hk represents Webull Hong Kong (developer.webull.hk).

See .env.example for full configuration template.

Available Tools

Market Data

Category	Tools	Region
Stock	`get_stock_tick`, `get_stock_snapshot`, `get_stock_quotes`, `get_stock_footprint`, `get_stock_bars`, `get_stock_bars_single`	US, HK
Futures	`get_futures_tick`, `get_futures_snapshot`, `get_futures_depth`, `get_futures_bars`, `get_futures_footprint`	US
Crypto	`get_crypto_snapshot`, `get_crypto_bars`	US
Event	`get_event_tick`, `get_event_snapshot`, `get_event_depth`, `get_event_bars`	US

Trading

Category	Tools	Region
Account	`get_account_list`	US, HK
Assets	`get_account_balance`, `get_account_positions`	US, HK
Instrument	`get_instruments`, `get_futures_instruments`, `get_futures_products`, `get_crypto_instruments`, `get_event_series`, `get_event_instruments`, `get_event_categories`, `get_event_events`	varies
Stock Order	`place_stock_order`, `preview_stock_order`, `replace_stock_order`	US, HK
Combo Order	`place_stock_combo_order` (OTO/OCO/OTOCO)	US
Option Order	`place_option_single_order`, `preview_option_order`, `replace_option_order`	US, HK
Option Strategy	`place_option_strategy_order`	US
Algo Order	`place_algo_order` (TWAP/VWAP/POV)	US
Futures Order	`place_futures_order`, `replace_futures_order`	US
Crypto Order	`place_crypto_order`	US
Event Order	`place_event_order`, `replace_event_order`	US
Order	`cancel_order`, `get_order_history`, `get_open_orders`, `get_order_detail`	US, HK

Region Differences

Feature	US	HK
Stock/Option Trading	✅	✅
Futures Trading	✅	❌
Crypto Trading	✅	❌
Event Contracts	✅	❌
Combo Orders	✅	❌
Option Strategies	✅	❌
Algo Orders	✅	❌
Markets	US	US, HK, CN
Order Types	LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, TRAILING_STOP_LOSS, etc.	LIMIT, MARKET, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, etc.

CLI Commands

webull-openapi-mcp --version    # Show version
webull-openapi-mcp init         # Initialize .env configuration
webull-openapi-mcp auth         # Authenticate (2FA accounts)
webull-openapi-mcp serve        # Start MCP server
webull-openapi-mcp status       # Show configuration status
webull-openapi-mcp tools        # List available tools

Security

Never share your AK/SK with AI models — Do not paste your App Key or App Secret into chat prompts, AI assistants, or any LLM conversation. These credentials should only be configured via environment variables or .env files, never exposed in plain text to the model.
Prefer env over .env files — Pass credentials via the MCP client's env field (in mcp.json) rather than a .env file in your workspace. The env field injects credentials as process environment variables, which the AI model cannot access. A .env file in your workspace could be read by the AI assistant through IDE file access.
Credential isolation — AK/SK are used only inside the MCP server process for SDK initialization and request signing. They never appear in tool outputs, logs, or error messages.
Review before trading — Always review order details proposed by the AI before confirming. Use preview_stock_order / preview_option_order before placing orders.
Use toolset filtering — Set WEBULL_TOOLSETS=account,market-data to disable trading tools entirely if you only need read-only access.
Default sandbox — The server defaults to UAT (sandbox) environment. You must explicitly set WEBULL_ENVIRONMENT=prod for live trading.
Dependency security — fastmcp is pinned to version 2.0.0. Users are responsible for monitoring and updating third-party dependencies for security patches. Review release notes before upgrading.

Troubleshooting

2FA Authentication Required

webull-openapi-mcp auth    # Approve in Webull app
webull-openapi-mcp serve   # Then start server

Device Not Registered

Open Webull mobile app → log in with your API account → complete device registration
Run webull-openapi-mcp auth

Market Data 401/403

Subscribe to quotes:

HK: webullapp.hk/quote | Guide
US: webullapp.com/quote | Guide

Token Expired

rm -rf ./conf/token.txt
webull-openapi-mcp auth

Project Structure

webull-mcp-server/
├── webull_openapi_mcp/
│   ├── cli.py              # CLI commands
│   ├── server.py           # MCP server
│   ├── sdk_client.py       # Webull SDK adapter
│   ├── config.py           # Configuration management
│   ├── region_config.py    # Region-specific settings
│   ├── guards.py           # Order validation
│   ├── audit.py            # Audit logging
│   ├── errors.py           # Error handling
│   ├── formatters.py       # Response formatting
│   ├── constants.py        # Enum constants
│   └── tools/
│       ├── market_data/    # Stock, futures, crypto, event market data
│       └── trading/        # Account, order, instrument tools
├── tests/                  # Unit & property-based tests
├── conf/                   # Token storage
├── .env.example            # Configuration template
├── DISCLAIMER.md           # Full disclaimer
└── pyproject.toml          # Package configuration

License

Apache License 2.0 — see LICENSE for details.

Navigation Menu

Repository navigation

About

Repository files navigation

⚠️ DEPRECATED — This project is no longer maintained

Webull OpenAPI MCP Server

⚠️ Disclaimer

Features

Example Prompts

Prerequisites

Installation

Option 1: uvx (Recommended)

Option 2: pip

Option 3: Local Development

Quick Start

1. Initialize Configuration

2. Authenticate

3. Start the Server

Client Configuration

Kiro / Cursor / Claude Desktop

Configuration

Available Tools

Market Data

Trading

Region Differences

CLI Commands

Security

Troubleshooting

2FA Authentication Required

Device Not Registered

Market Data 401/403

Token Expired

Project Structure

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
tests		tests
webull_openapi_mcp		webull_openapi_mcp
.env.example		.env.example
.gitignore		.gitignore
DISCLAIMER.md		DISCLAIMER.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Latest commit

History

Folders and files

Repository files navigation

⚠️ DEPRECATED — This project is no longer maintained

Webull OpenAPI MCP Server

⚠️ Disclaimer

Features

Example Prompts

Prerequisites

Installation

Option 1: uvx (Recommended)

Option 2: pip

Option 3: Local Development

Quick Start

1. Initialize Configuration

2. Authenticate

3. Start the Server

Client Configuration

Kiro / Cursor / Claude Desktop

Configuration

Available Tools

Market Data

Trading

Region Differences

CLI Commands

Security

Troubleshooting

2FA Authentication Required

Device Not Registered

Market Data 401/403

Token Expired

Project Structure

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages