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.
Alimenter votre agent
La commande propre à l'éditeur. Ce n'est pas un endpoint PlugMCP.
Host a copy with our keys and logs.
uvx webull-openapi-mcp==1.2.6Claude Code n'a pas de lien d'installation pour une commande locale. Copiez la commande ci-dessous et exécutez-la dans un terminal.
claude mcp add io.github.webull-inc-webull-openapi-mcp -- uvx webull-openapi-mcp==1.2.6À exécuter dans un terminal.
{ "mcpServers": { "io.github.webull-inc-webull-openapi-mcp": { "command": "uvx", "args": [ "webull-openapi-mcp==1.2.6" ] } }}claude_desktop_config.json
URL distante ou commande sur votre machine ? Ce qui distingue les deux installations
Exécuter sur PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
LancerThe 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
Community
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"
]
}
}
}
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=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), andWEBULL_REGION_ID=zarepresents Webull South Africa (developer.webull.co.za).
See .env.example for full configuration template.
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 all 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 3.0.4. 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, MY, UK, MX, BR, ZA)
│ ├── 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
│ │ ├── community.py # Community posts, comments, hot stocks
│ │ ├── 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.
MCP server for Webull OpenAPI: trading and market data access for AI assistants
{ "mcpServers": { "io.github.webull-inc-webull-openapi-mcp": { "command": "uvx", "args": [ "webull-openapi-mcp==1.2.6" ] } }}Outils
Pas encore de liste d'outils. Les serveurs distants en obtiennent une après le premier contrôle d'état.
FAQ
Copiez sur cette page la configuration stdio pour Cursor, Claude Desktop, Claude Code ou VS Code. Elle utilise l'installation de l'éditeur, pas un proxy PlugMCP.
Aucune variable d'environnement requise n'est indiquée sur cette fiche.
Webull OpenAPI s'exécute en local via stdio.
Dernière vérification : 2026-11-10. MCP server for Webull OpenAPI: trading and market data access for AI assistants