
Research
/Security News
Popular npm Packages in the keyv and Cacheable Namespaces Compromised in Active Supply Chain Attack
Popular npm packages keyv and cacheable compromised.
webull-openapi-mcp
Advanced tools
MCP Server for Webull OpenAPI - enables AI assistants to securely access Webull trading and market data
MCP Server for Webull OpenAPI — enables AI assistants (Cursor, Claude Desktop, Kiro, etc.) to securely access Webull trading and market data.
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.
Here are some prompts you can use with your AI assistant:
Market Data
Screener
Watchlist
Fundamental & Analyst
Financial Statements
Account & Portfolio
Stock Trading
Options Trading
Option Market Data
Order Management
HK Market
App Key and App SecretBefore 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
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).
uvx webull-openapi-mcp serve
That's it. Your AI assistant can now access Webull trading and market data.
No installation needed. uvx downloads and runs the package directly from PyPI:
uvx webull-openapi-mcp serve
pip install webull-openapi-mcp
webull-openapi-mcp serve
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
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-openapi-mcp",
"python", "-m", "webull_openapi_mcp", "serve",
"--env-file", "/path/to/.env"
]
}
}
}
| 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, hk, jp, sg, th, my, uk, mx, br, eu, za, or au | us |
WEBULL_TOOLSETS | Enabled tool categories (comma-separated). Valid values: account, market-data, trading, instrument | (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_NOTIONAL_JPY | Max order value for JP market (JPY) | 1500000 |
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=usrepresents Webull US (developer.webull.com),WEBULL_REGION_ID=hkrepresents Webull Hong Kong (developer.webull.hk),WEBULL_REGION_ID=jprepresents Webull Japan (developer.webull.co.jp),WEBULL_REGION_ID=sgrepresents Webull Singapore (developer.webull.com.sg),WEBULL_REGION_ID=threpresents Webull Thailand (developer.webull.co.th),WEBULL_REGION_ID=myrepresents Webull Malaysia (developer.webull.com.my),WEBULL_REGION_ID=ukrepresents Webull UK (developer.webull-uk.com),WEBULL_REGION_ID=mxrepresents Webull Mexico (developer.webull.com.mx),WEBULL_REGION_ID=brrepresents Webull Brazil (developer.webull.com.br),WEBULL_REGION_ID=eurepresents Webull EU (developer.webull.eu),WEBULL_REGION_ID=zarepresents Webull South Africa (developer.webull.co.za), andWEBULL_REGION_ID=aurepresents Webull Australia (developer.webull.com.au).
See .env.example for full configuration template.
| Category | Tools | Region |
|---|---|---|
| Stock | get_stock_tick, get_stock_snapshot, get_stock_quotes, get_stock_footprint, get_stock_bars, get_stock_bars_single, get_stock_noii_bars, get_stock_noii_snapshot | All |
| Futures | get_futures_tick, get_futures_snapshot, get_futures_depth, get_futures_bars, get_futures_footprint | US, HK |
| Crypto | get_crypto_snapshot, get_crypto_bars | US |
| Option | get_option_tick, get_option_snapshot, get_option_bars | US, HK, JP |
| Event | get_event_tick, get_event_snapshot, get_event_depth, get_event_bars | US |
| Screener | get_gainers_losers, get_most_active | All |
| Screener (Sectors/Dividend/52W) | get_market_sectors, get_market_sectors_detail, get_high_dividend, get_52_week_high_low | US, HK, JP |
| Watchlist | get_watchlists, create_watchlist, update_watchlist, delete_watchlist, get_watchlist_instruments, add_watchlist_instruments, remove_watchlist_instruments, update_watchlist_instruments | All |
| Category | Tools | Region |
|---|---|---|
| Instrument | get_instruments, get_option_contracts, get_futures_instruments, get_futures_products, get_crypto_instruments, get_event_series, get_event_instruments, get_event_categories, get_event_events | varies |
| Fundamental | get_company_profile, get_analyst_rating, get_analyst_target_price | All |
| Stock Fundamentals | get_stock_capital_flow, get_stock_filings, get_stock_earnings_calendar, get_stock_dividend_calendar, get_stock_forecast_eps, get_stock_industry_comparison | US, HK, JP |
| Fund Fundamentals | get_fund_rating, get_fund_performance, get_fund_allocation, get_fund_holdings, get_fund_brief, get_fund_dividends, get_fund_splits, get_fund_net_value, get_fund_files | US, HK, JP |
| Financial Statements | get_financial_alert, get_financial_indicators, get_income_statement, get_balance_sheet, get_cash_flow | US, HK, JP |
| Category | Tools | Region |
|---|---|---|
| Account | get_account_list | All |
| Assets | get_account_balance, get_account_positions, get_account_position_details (JP only) | All |
| Stock Order | place_stock_order, preview_stock_order, replace_stock_order | All |
| 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, HK |
| 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 | All |
| Feature | US | HK | JP | SG | TH | MY | UK | MX | BR | EU | ZA | AU |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Stock Trading | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Option Trading | Yes | Yes | No | No | No | No | No | No | No | No | No | No |
| Futures Trading | Yes | Yes | No | No | No | No | No | No | No | No | No | No |
| Crypto Trading | Yes | No | No | No | No | No | No | No | No | No | No | No |
| Event Contracts | Yes | No | No | No | No | No | No | No | No | No | No | No |
| Combo Orders | Yes | No | No | No | No | No | No | No | No | No | No | No |
| Option Strategies | Yes | No | No | No | No | No | No | No | No | No | No | No |
| Algo Orders | Yes | No | No | No | No | No | No | No | No | No | No | No |
| Screener (Gainers/Losers/Active) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Screener (Sectors/Dividend/52W) | Yes | Yes | Yes | No | No | No | No | No | No | No | No | No |
| Watchlist | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Fundamental (Company/Analyst) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Stock/Fund Fundamentals | Yes | Yes | Yes | No | No | No | No | No | No | No | No | No |
| Financial Statements | Yes | Yes | Yes | No | No | No | No | No | No | No | No | No |
| NOII (Auction Imbalance) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Markets | US | US, HK, CN | US, JP | US | US | US | US | US | US | US | US | US |
| Instrument Categories | US_STOCK, US_ETF | US_STOCK, US_ETF, HK_STOCK, CN_STOCK | US_STOCK, US_ETF | US_STOCK, US_ETF | US_STOCK, US_ETF | US_STOCK, US_ETF | US_STOCK, US_ETF | US_STOCK, US_ETF | US_STOCK, US_ETF | US_STOCK, US_ETF | US_STOCK, US_ETF | US_STOCK, US_ETF |
| Order Types | LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT, TRAILING_STOP_LOSS, etc. | LIMIT, MARKET, ENHANCED_LIMIT, AT_AUCTION, AT_AUCTION_LIMIT, etc. | JP market: LIMIT, MARKET — US market: LIMIT, MARKET, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT | MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT |
| Time-in-Force | DAY, GTC | US market: DAY, GTC, GTD — HK market: DAY, GTC — CN market: DAY | JP market: DAY — US market: DAY, GTC, GTD | DAY, GTC | DAY, GTC | DAY, GTC | DAY, GTC | DAY, GTC | DAY, GTC | DAY, GTC | DAY, GTC | DAY, GTC |
| Trading Sessions | ALL, CORE, NIGHT | CORE, ALL_DAY, NIGHT, ALL | CORE, ALL, NIGHT, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY | NIGHT, ALL, CORE, ALL_DAY |
| JP Order Fields | — | — | account_tax_type required (GENERAL or SPECIFIC); margin_type (ONE_DAY or INDEFINITE) and position_intent optional margin-account-only fields; close_contracts optional | — | — | — | — | — | — | — | — | — |
Note: Screener (Gainers/Losers/Active), Fundamental (Company/Analyst), and NOII currently only support querying US stock data (
US_STOCKcategory). Stock/Fund Fundamentals, Financial Statements, and the extended Screener (Sectors/Dividend/52W) are available in US, HK, and JP regions; supportedcategoryvalues vary by endpoint (commonlyUS_STOCK,HK_STOCK,CN_STOCK,JP_STOCK). Watchlist supports US stocks and HK stocks.
If installed via pip:
webull-openapi-mcp --version # Show version
webull-openapi-mcp init [--env-file PATH] # Initialize .env configuration
webull-openapi-mcp init --app-key KEY --app-secret SECRET --environment prod
webull-openapi-mcp auth [--env-file PATH] # Authenticate (2FA accounts)
webull-openapi-mcp serve [--env-file PATH] # Start MCP server
webull-openapi-mcp status [--env-file PATH] # Show configuration status
webull-openapi-mcp tools [--env-file PATH] # List available tools
If using uvx (prefix with uvx):
uvx webull-openapi-mcp auth
uvx webull-openapi-mcp serve
uvx webull-openapi-mcp status
If local development (prefix with uv run python -m webull_openapi_mcp):
uv run python -m webull_openapi_mcp auth
uv run python -m webull_openapi_mcp serve
All commands accept --env-file PATH to specify a custom .env file location (default: .env in the current directory).
.env files, never exposed in plain text to the model.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.preview_stock_order / preview_option_order before placing orders.WEBULL_TOOLSETS=account,market-data to disable trading tools entirely if you only need read-only access. Valid toolsets: account, market-data, trading, instrument.WEBULL_ENVIRONMENT=prod for live trading.fastmcp is pinned to version 3.0.2 and webull-openapi-python-sdk is pinned to 2.0.16. Users are responsible for monitoring and updating third-party dependencies for security patches. Review release notes before upgrading.# If installed via pip:
webull-openapi-mcp auth
# If using uvx:
uvx webull-openapi-mcp auth
# If local development:
uv run python -m webull_openapi_mcp auth
Approve the request in your Webull app, then start the server.
# If installed via pip:
webull-openapi-mcp auth
# If using uvx:
uvx webull-openapi-mcp auth
Subscribe to quotes:
rm -rf ./conf/token.txt
# Then re-authenticate:
webull-openapi-mcp auth # pip
uvx webull-openapi-mcp auth # uvx
On Windows, authentication error messages may display garbled characters if the console encoding is not UTF-8. The server automatically detects the console encoding and falls back to ASCII-only output on non-UTF-8 terminals. If you still see garbled text, run:
chcp 65001
This switches the Windows console to UTF-8 before starting the server.
webull-openapi-mcp/
├── webull_openapi_mcp/
│ ├── __init__.py # Package version
│ ├── __main__.py # python -m entry point
│ ├── cli.py # CLI commands (init, auth, serve, status, tools)
│ ├── server.py # MCP server setup and tool registration
│ ├── sdk_client.py # Webull SDK adapter (ApiClient, TradeClient, DataClient)
│ ├── config.py # Configuration loading and validation
│ ├── region_config.py # Region-specific settings (US, HK, JP, SG, TH, MY, UK, MX, BR)
│ ├── guards.py # Order validation (price, quantity, notional, region rules)
│ ├── audit.py # Audit logging for order operations
│ ├── errors.py # Exception definitions and SDK error handling
│ ├── formatters.py # Response formatting with disclaimer
│ ├── constants.py # Enum constants (sides, order types, strategies)
│ └── tools/
│ ├── __init__.py # Tool registration exports
│ ├── market_data/
│ │ ├── stock.py # Stock market data (snapshot, quotes, bars, tick, footprint, NOII)
│ │ ├── option.py # Option market data (tick, snapshot, bars)
│ │ ├── futures.py # Futures market data
│ │ ├── crypto.py # Crypto market data
│ │ ├── event.py # Event contract market data
│ │ ├── screener.py # Gainers/losers, most active, market sectors, high dividend, 52-week high/low
│ │ ├── watchlist.py# Watchlist CRUD and instrument management
│ │ ├── fundamental.py # Company profile, analyst data; stock & fund fundamentals (US/HK/JP)
│ │ └── financial.py # Financial statements: alert, indicators, income, balance sheet, cash flow (US/HK/JP)
│ └── trading/
│ ├── account.py # Account list
│ ├── assets.py # Balance, positions
│ ├── instrument.py # Instrument lookup
│ ├── order.py # Order query, cancel (shared across asset types)
│ ├── stock_order.py # Stock order place, preview, replace
│ ├── option_order.py # Option single-leg and strategy orders
│ ├── futures_order.py # Futures order place, replace
│ ├── crypto_order.py # Crypto order place
│ └── event_order.py # Event contract order place, replace
├── tests/ # Unit and property-based tests
├── conf/ # Token storage (auto-generated)
├── .env.example # Configuration template
├── DISCLAIMER.md # Full disclaimer
├── pyproject.toml # Package configuration
└── LICENSE # Apache 2.0
Apache License 2.0 — see LICENSE for details.
FAQs
MCP Server for Webull OpenAPI - enables AI assistants to securely access Webull trading and market data
We found that webull-openapi-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Research
/Security News
Popular npm packages keyv and cacheable compromised.

Security News
A misconfiguration gave three Anthropic models internet access, and one, believing it was in a simulation, shipped a credential-stealing package to PyPI.

Security News
/Company News
Socket has joined the new Composer and Packagist sponsorship program as a launch sponsor, supporting the team that keeps PHP's package ecosystem secure.