Webull MCP Server

Webull MCP Server enables AI assistants (Cursor, Claude Desktop, Kiro, etc.) to securely access Webull OpenAPI trading and market data capabilities via the Model Context Protocol (MCP).

Source code: webull-inc/webull-openapi-mcp

---

What is Webull MCP

Webull MCP Server is a server built on the Model Context Protocol that wraps Webull OpenAPI capabilities into tools callable by AI assistants. With MCP, you can use natural language in your AI coding assistant to:

• Query real-time market data
• View account balances and positions
• Place, modify, and cancel orders
• Query order history and order details

Architecture Overview

---

Prerequisites

API Credentials (App Key and App Secret)

Production

Apply at: Individual Application Guide

Sandbox (Test)

No application required. Use the publicly shared test credentials to get started immediately. See SDKs and Tools.

Other Requirements

• Market Data Subscription (if market data is needed): webull.co.jp/pricing | Subscription Guide
• uvx (Python 3.10+ required) — uv Installation Guide
• MCP-compatible AI Client — e.g. Cursor, Claude Desktop, Kiro

---

Setup Steps

Step 1: Install

Ensure Python 3.10+ and uvx are installed. No need to manually install Webull MCP Server — your AI client will automatically download and launch it via uvx.

Step 2: Configure AI Client

Add the following configuration to your AI client's MCP config file. Replace your_app_key and your_app_secret with the credentials obtained in the prerequisites:

Cursor

Edit .cursor/mcp.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": "jp",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.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": "jp",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

Kiro

Edit .kiro/settings/mcp.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": "jp",
        "WEBULL_ENVIRONMENT": "prod"
      }
    }
  }
}

tip

For sandbox environment, set WEBULL_ENVIRONMENT to uat.

Step 3: Authenticate

note

This step is only required if your account has Two-Factor Authentication enabled.

Complete a one-time authentication in the terminal before first use:

uvx webull-openapi-mcp auth

Authentication flow:

After approving the request in the Webull App, the token is saved locally. The token is valid for 15 days and auto-refreshes on use.

Step 4: Verify Connection

Restart your AI client and try the following in a conversation:

Get my account list

If your account information is returned, Webull MCP is successfully connected.

---

Usage Examples

Market Data

Get a real-time snapshot for AAPL

Show me AAPL's daily bars for the last 5 days

Trading

Buy 100 shares of AAPL at limit price $250 with GENERAL tax account

Place a market order to sell 50 shares of TSLA with SPECIFIC tax account

---

Available Endpoints

Endpoint	Description
get_account_list	Get all linked accounts
get_account_balance	Get account balance, buying power, and cash details
get_account_positions	Get current positions and holdings
get_account_position_details	[JP Only] Get contract-level position details by instrument
get_stock_tick	Get stock tick-by-tick trade data
get_stock_snapshot	Get real-time stock/ETF snapshot
get_stock_quotes	Get real-time bid/ask quotes with depth
get_stock_footprint	Get stock large order footprint (order flow)
get_stock_bars	Get stock OHLCV bars in batch
get_stock_bars_single	Get OHLCV bars for a single stock
get_instruments	Get stock/ETF instrument info
place_stock_order	Place a stock order
preview_stock_order	Preview a stock order without submitting
replace_stock_order	Modify an existing stock order
cancel_order	Cancel an unfilled order
get_order_history	Get historical orders
get_open_orders	Get all current open/pending orders
get_order_detail	Get single order details

---

JP-Specific Order Parameters

When placing orders in the JP region, the following additional parameters are available:

Parameter	Required	Values	Description
account_tax_type	Yes	GENERAL, SPECIFIC	Tax account type for the order
margin_type	No (margin accounts only)	ONE_DAY, INDEFINITE	Margin loan duration
position_intent	No (margin accounts only)	BUY_TO_OPEN, BUY_TO_CLOSE, SELL_TO_OPEN, SELL_TO_CLOSE	Position direction for margin trades
close_contracts	No	Array of contract objects	Specific contracts to close (for position closing)

Configuration Parameters

Variable	Description	Default
WEBULL_APP_KEY	App Key (required)	—
WEBULL_APP_SECRET	App Secret (required)	—
WEBULL_ENVIRONMENT	uat (sandbox) or prod (production)	uat
WEBULL_REGION_ID	Set to jp	us
WEBULL_TOOLSETS	Enabled tool categories (comma-separated)	all enabled
WEBULL_MAX_ORDER_NOTIONAL_JPY	Max order notional for JP market (JPY)	1500000
WEBULL_MAX_ORDER_NOTIONAL_USD	Max order notional for US market (USD)	10000
WEBULL_MAX_ORDER_QUANTITY	Max order quantity per order	1000
WEBULL_SYMBOL_WHITELIST	Allowed symbols whitelist (comma-separated)	no restriction

For read-only access (market data + account only), set WEBULL_TOOLSETS=account,market-data to disable trading tools.

---

Security Recommendations

• Never share your App Key, App Secret, or Token via chat with an AI model. These credentials should only be passed to the MCP Server process via the env field in mcp.json, never as conversation content.
• Use preview_stock_order before placing orders to verify estimated costs.
• Use WEBULL_SYMBOL_WHITELIST to restrict tradable symbols.

---

Disclosure

Webull MCP Server provides information solely for reference purposes and does not constitute investment advice. Trading in securities and other financial instruments involves substantial risk of loss. All trading decisions are made at your own discretion and risk. You are solely responsible for verifying order details before execution. This software is provided "as is" without warranty of any kind.

---

Related Links

• Webull OpenAPI Docs: developer.webull.co.jp
• MCP Protocol: modelcontextprotocol.io
• Python SDK: pip install webull-openapi-python-sdk