# Webull Local MCP Server

> Webull Local 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](https://github.com/webull-inc/webull-openapi-mcp)

---
 
## What is Webull Local MCP

Webull Local MCP Server is a server built on the [Model Context Protocol](https://modelcontextprotocol.io/) 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

```mermaid
sequenceDiagram
    participant U as User
    participant AI as AI Assistant (Claude / Cursor / Kiro)
    participant MCP as Webull MCP Server
    participant SDK as Webull Python SDK
    participant API as Webull OpenAPI

    U->>AI: Natural Language Command (e.g. Get AAPL quote)
    AI->>MCP: MCP Protocol Call (stdio)
    MCP->>SDK: Invoke SDK Method
    SDK->>API: REST API Request (Signed Auth)
    API-->>SDK: Return Data
    SDK-->>MCP: Parse Result
    MCP-->>AI: Formatted Response
    AI-->>U: Readable Reply
```

---

## Prerequisites

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

### API Credentials (App Key and App Secret)

<Tabs groupId="environment">
  <TabItem value="prod" label="Production" default>

Apply based on your account type:

Individual users: [Individual Application Guide](../authentication/IndividualApplicationAPI.md)

Institutional users: [Institution Application Guide](../authentication/apply.md)

  </TabItem>
  <TabItem value="sandbox" label="Sandbox (Test)">

No application required. Use the publicly shared test credentials to get started immediately. See [SDKs and Tools](../sdk.md).

  </TabItem>
</Tabs>

### Other Requirements

- **Market Data Subscription** (if market data is needed): [webullapp.com/quote](https://www.webullapp.com/quote) | [Subscription Guide](../market-data-api/subscribe-quotes.md)
- **uvx** (Python 3.10+ required) — [uv Installation Guide](https://docs.astral.sh/uv/getting-started/installation/)
- **MCP-compatible AI Client** — e.g. [Cursor](https://cursor.com), [Claude Desktop](https://claude.ai/download), [Kiro](https://kiro.dev)

---

## Setup Steps

```mermaid
flowchart LR
    S1(Install) --> S2(Configure AI Client) --> S3(Auth 2FA) --> S4(Verify)
```

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

<Tabs groupId="ai-client">
  <TabItem value="cursor" label="Cursor" default>

Edit `.cursor/mcp.json`:

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

  </TabItem>
  <TabItem value="claude" label="Claude Desktop">

Edit `claude_desktop_config.json`:

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

  </TabItem>
  <TabItem value="kiro" label="Kiro">

Edit `.kiro/settings/mcp.json`:

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

  </TabItem>
</Tabs>

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

```bash
uvx webull-openapi-mcp auth
```

Authentication flow:

```mermaid
sequenceDiagram
    participant CLI as Terminal
    participant API as Webull API
    participant App as Webull App (Mobile)

    CLI->>API: Request Token Creation
    API-->>CLI: Return PENDING Status
    CLI->>CLI: Waiting for 2FA Approval...
    App->>API: User Approves in App
    API-->>CLI: Token Status → NORMAL
    CLI->>CLI: Save Token Locally
    Note over CLI:  Auth Complete, Token Valid for 15 Days
```

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 market price
```

```
Buy 10 shares of TSLA at market price
```

---

## Available Endpoints

| Endpoint | Description |
|----------|-------------|
| `add_watchlist_instruments` | Add instruments to a watchlist. |
| `cancel_order` | Cancel an unfilled order (stocks, options, futures, crypto, event contracts). |
| `create_watchlist` | Create a new watchlist. |
| `delete_watchlist` | Delete a watchlist and all its instruments (irreversible). |
| `get_52_week_high_low` | Get 52-week high/low stocks ranking. |
| `get_account_balance` | Get account balance (net liquidation, buying power, cash, market value, P&L). |
| `get_account_list` | Get all linked accounts. |
| `get_account_positions` | Get account positions list. |
| `get_analyst_rating` | Get analyst rating for a security (strong buy/buy/hold/sell counts). |
| `get_analyst_target_price` | Get analyst consensus target price for a security. |
| `get_balance_sheet` | Get balance sheet for a stock across periods. |
| `get_cash_flow` | Get cash flow statement for a stock across periods. |
| `get_company_profile` | Get company profile (business description, industry, CEO, employees, etc.). |
| `get_crypto_bars` | Get cryptocurrency OHLCV bars. |
| `get_crypto_instruments` | Get cryptocurrency instrument info. |
| `get_crypto_snapshot` | Get cryptocurrency real-time snapshot. |
| `get_event_bars` | Get event contract OHLCV bars. |
| `get_event_categories` | Get event contract category list. |
| `get_event_depth` | Get event contract order book depth. |
| `get_event_events` | Get events within a series. |
| `get_event_instruments` | Get event contract instruments by series. |
| `get_event_series` | Get event contract series (recurring event templates). |
| `get_event_snapshot` | Get event contract real-time snapshot. |
| `get_event_tick` | Get event contract tick-by-tick trade data. |
| `get_financial_alert` | Get financial alert (next report estimates vs last year). |
| `get_financial_indicators` | Get financial indicators (key ratios/metrics) for a stock. |
| `get_fund_allocation` | Get fund asset allocation by date. |
| `get_fund_brief` | Get fund brief information. |
| `get_fund_dividends` | Get fund dividend history. |
| `get_fund_files` | Get fund files/documents. |
| `get_fund_holdings` | Get fund top 10 holdings. |
| `get_fund_net_value` | Get fund net value (NAV) history. |
| `get_fund_performance` | Get fund performance returns over multiple horizons. |
| `get_fund_rating` | Get fund rating history. |
| `get_fund_splits` | Get fund split history. |
| `get_futures_bars` | Get futures OHLCV bars in batch. |
| `get_futures_depth` | Get futures order book depth. |
| `get_futures_footprint` | Get futures large order footprint (order flow). |
| `get_futures_instruments` | Get futures instrument info. |
| `get_futures_product_class` | Get all futures product classification groups. |
| `get_futures_products` | Get all futures products and product codes. |
| `get_futures_snapshot` | Get futures real-time snapshot. |
| `get_futures_tick` | Get futures tick-by-tick trade data. |
| `get_gainers_losers` | Get top gainers or losers ranking by price change. |
| `get_high_dividend` | Get high dividend stocks ranking. |
| `get_income_statement` | Get income statement for a stock across periods. |
| `get_instruments` | Get stock/ETF instrument info. |
| `get_market_sectors` | Get market sector overview ranking. |
| `get_market_sectors_detail` | Get stock list and statistics for a specific market sector. |
| `get_most_active` | Get most actively traded stocks ranking. |
| `get_open_orders` | Get all current open/pending orders. |
| `get_order_detail` | Get single order details. |
| `get_order_history` | Get historical orders (default last 7 days). |
| `get_stock_bars` | Get stock OHLCV bars in batch (multiple symbols). |
| `get_stock_bars_single` | Get OHLCV bars for a single stock. |
| `get_stock_capital_flow` | Get capital flow distribution for a stock by date. |
| `get_stock_dividend_calendar` | Get dividend calendar for a stock. |
| `get_stock_earnings_calendar` | Get earnings calendar for a stock. |
| `get_stock_filings` | Get SEC filings for a US stock (last 3 years). |
| `get_stock_forecast_eps` | Get forecast EPS for a stock. |
| `get_stock_footprint` | Get stock large order footprint (order flow). |
| `get_stock_industry_comparison` | Get industry comparison for a stock (up to 20 peers). |
| `get_stock_noii_bars` | Get NOII K-line data for a stock (opening/closing auction imbalance). |
| `get_stock_noii_snapshot` | Get latest NOII snapshot for a stock during auction phases. |
| `get_stock_quotes` | Get real-time stock bid/ask quotes with depth. |
| `get_stock_snapshot` | Get real-time stock/ETF snapshot (supports multiple symbols). |
| `get_stock_tick` | Get stock tick-by-tick trade data. |
| `get_watchlist_instruments` | Get all instruments in a watchlist. |
| `get_watchlists` | Get all watchlists for the current user. |
| `place_algo_order` | Place an algorithmic order (TWAP, VWAP, POV). |
| `place_crypto_order` | Place a cryptocurrency order. |
| `place_event_order` | Place an event contract order. |
| `place_futures_order` | Place a futures order. |
| `place_option_single_order` | Place a single-leg option order. |
| `place_option_strategy_order` | Place a multi-leg option strategy order. |
| `place_stock_combo_order` | Place a combo stock order (OTO/OCO/OTOCO). |
| `place_stock_order` | Place a stock order (single, non-combo). |
| `preview_option_order` | Preview an option order without submitting. |
| `preview_stock_order` | Preview a stock order without submitting. |
| `remove_watchlist_instruments` | Remove instruments from a watchlist. |
| `replace_event_order` | Modify an existing event contract order. |
| `replace_futures_order` | Modify an existing futures order. |
| `replace_option_order` | Modify an existing option order. |
| `replace_stock_order` | Modify an existing stock order. |
| `update_watchlist` | Update an existing watchlist's name or sort order. |
| `update_watchlist_instruments` | Update the sort order of instruments in a watchlist. |

---

## 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` | `us` | `us` |
| `WEBULL_TOOLSETS` | Enabled tool categories (comma-separated) | all enabled |
| `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` / `preview_option_order` before placing orders.
- Use `WEBULL_SYMBOL_WHITELIST` to restrict tradable symbols.

---

## Disclosure

Webull Local MCP Server provides information solely for reference purposes and does not constitute investment advice. Trading in securities, options, cryptocurrencies, 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.com](https://developer.webull.com/apis)
- MCP Protocol: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
- Python SDK: `pip install webull-openapi-python-sdk`