# Webull Cloud MCP Server

> Webull Cloud MCP is a fully managed MCP service hosted by Webull.

> Unlike Local MCP, users do not need to install MCP Server, configure AI clients, manage API credentials, or perform local authentication.

> Users simply connect their Webull account through OAuth authorization and immediately access Webull capabilities from supported AI platforms.

> MCP Server URL Is: `https://api.webull.com/mcp`(configuration link, cannot be openned directly).

---

## Quick Navigation

- [Architecture Overview](#architecture-overview-cloud)
- [Authorization Flow](#authorization-flow)
- [Account & Capability Authorization](#account-capability-authorization)
- [Market Data Permissions](#market-data-permissions)
- [How To Connect Cloud MCP](#connect-cloud-mcp)
- [How To Place Order Using MCP](#place-order-mcp)

---

## Architecture Overview {#architecture-overview-cloud}

```mermaid
sequenceDiagram
    participant User
    participant AI as AI Platform
    participant OAuth as Webull OAuth
    participant MCP as Webull Cloud MCP
    participant API as Webull OpenAPI

    User->>AI: Connect Webull MCP
    AI->>OAuth: OAuth Login
    OAuth-->>AI: Authorization Success

    AI->>MCP: MCP Tool Request
    MCP->>API: OpenAPI Request
    API-->>MCP: Response
    MCP-->>AI: Tool Result
    AI-->>User: Natural Language Response
```

---

## Authorization Flow

Webull Cloud MCP uses OAuth Authorization Code Flow.

Authentication supports:

- Mobile Number + Password + Trading Password
- Email + Password + Trading Password

---

## Account & Capability Authorization {#account-capability-authorization}

After successful login, users enter a unified authorization page.

### Account Authorization

Users may authorize one or more accounts.

Example:

- Individual Cash
- Margin Account
- IRA Account
- Futures Account

Only selected accounts will be accessible through MCP.

### Capability Authorization

Users may authorize capability groups independently.

Examples:

| Capability | Description |
|------------|------------|
| Account Infos | View account information, assets, and positions. Allows the AI assistant to access your authorized account details, including account profile, account balances, buying power, cash holdings, and current positions. |
| Order Query | View order history and trading activities. Allows the AI assistant to access your order records, execution history, and transaction status for authorized accounts. |
| Market Data | Access real-time and historical market data. Allows the AI assistant to retrieve market quotes, price movements, and related market information for supported securities, as well as screeners, market sentiment, unusual activities, and market news. |
| Security Master | Access security reference and instrument information. Allows the AI assistant to retrieve basic information about supported financial instruments, including stocks, ETFs, options, futures, and other securities, along with fundamentals, financial statements, and institution/insider data. |

This follows the Principle of Least Privilege.

Only explicitly authorized capabilities are available to AI platforms.

### Market Data Permissions

Cloud MCP market data permissions are the same as the market data permissions of your Webull App account. The level, coverage, and real-time or delayed status of the data you receive through Cloud MCP match what you can see in the Webull App.

:::caution
OpenAPI market data subscriptions cannot be used with Cloud MCP. To access real-time or advanced market data through Cloud MCP (for example, option market data), subscribe in the Webull App.
:::

### Available Endpoints

| Endpoint | Description | Permissions |
|----------|-------------|-------------|
| `add_watchlist_instruments` | Add symbols to a watchlist | Non-Trading |
| `create_watchlist` | Create a new watchlist | Non-Trading |
| `delete_watchlist` | Delete a watchlist | Non-Trading |
| `get_account_balance` | Get account balances and assets | Non-Trading |
| `get_account_list` | Get all trading accounts | Non-Trading |
| `get_account_positions` | Get account holdings and positions | Non-Trading |
| `get_analyst_rating` | Get analyst ratings for a security | Non-Trading |
| `get_analyst_target_price` | Get analyst target prices for a security | Non-Trading |
| `get_company_profile` | Get company information and business details | Non-Trading |
| `get_crypto_bars` | Get historical crypto price data | Non-Trading |
| `get_crypto_instruments` | Get cryptocurrency information | Non-Trading |
| `get_crypto_snapshot` | Get real-time crypto market data | Non-Trading |
| `get_event_bars` | Get historical event contract data | Non-Trading |
| `get_event_categories` | Get event market categories | Non-Trading |
| `get_event_depth` | Get event contract order book data | Non-Trading |
| `get_event_events` | Get events in an event series | Non-Trading |
| `get_event_instruments` | Get event contract information | Non-Trading |
| `get_event_series` | Get event market series | Non-Trading |
| `get_event_snapshot` | Get real-time event market data | Non-Trading |
| `get_event_tick` | Get event contract trade data | Non-Trading |
| `get_futures_bars` | Get historical futures price data | Non-Trading |
| `get_futures_depth` | Get futures order book data | Non-Trading |
| `get_futures_footprint` | Get futures capital flow data | Non-Trading |
| `get_futures_instruments` | Get futures contract information | Non-Trading |
| `get_futures_product_class` | Get futures product categories | Non-Trading |
| `get_futures_products` | Get futures product information | Non-Trading |
| `get_futures_snapshot` | Get real-time futures market data | Non-Trading |
| `get_futures_tick` | Get futures trade data | Non-Trading |
| `get_gainers_losers` | Get top gainers and losers | Non-Trading |
| `get_instruments` | Get stock and ETF information | Non-Trading |
| `get_most_active` | Get the most actively traded stocks | Non-Trading |
| `get_open_orders` | Get open and pending orders | Non-Trading |
| `get_order_detail` | Get details of an order | Non-Trading |
| `get_order_history` | Get historical orders | Non-Trading |
| `get_stock_bars` | Get historical price data for multiple stocks | Non-Trading |
| `get_stock_bars_single` | Get historical price data for a single stock | Non-Trading |
| `get_stock_footprint` | Get stock capital flow data | Non-Trading |
| `get_stock_quotes` | Get stock bid and ask quotes | Non-Trading |
| `get_stock_snapshot` | Get real-time stock market data | Non-Trading |
| `get_stock_tick` | Get stock trade data | Non-Trading |
| `get_stock_noii_bars` | Get NOII K-line data for a stock (opening/closing auction imbalance) | Non-Trading |
| `get_stock_noii_snapshot` | Get latest NOII snapshot for a stock during auction phases | Non-Trading |
| `get_watchlist_instruments` | Get symbols in a watchlist | Non-Trading |
| `get_watchlists` | Get all watchlists | Non-Trading |
| `remove_watchlist_instruments` | Remove symbols from a watchlist | Non-Trading |
| `update_watchlist` | Update a watchlist | Non-Trading |
| `update_watchlist_instruments` | Update symbols in a watchlist | Non-Trading |
| `get_stock_capital_flow` | Get capital flow distribution for a stock by date. | Non-Trading |
| `get_stock_filings` | Get SEC filings for a US stock (last 3 years). | Non-Trading |
| `get_stock_earnings_calendar` | Get earnings calendar for a stock. | Non-Trading |
| `get_stock_dividend_calendar` | Get dividend calendar for a stock. | Non-Trading |
| `get_stock_forecast_eps` | Get forecast EPS for a stock. | Non-Trading |
| `get_stock_industry_comparison` | Get industry comparison for a stock (up to 20 peers). | Non-Trading |
| `get_fund_rating` | Get fund rating history. | Non-Trading |
| `get_fund_performance` | Get fund performance returns over multiple horizons. | Non-Trading |
| `get_fund_allocation` | Get fund asset allocation by date. | Non-Trading |
| `get_fund_holdings` | Get fund top 10 holdings. | Non-Trading |
| `get_fund_brief` | Get fund brief information. | Non-Trading |
| `get_fund_dividends` | Get fund dividend history. | Non-Trading |
| `get_fund_splits` | Get fund split history. | Non-Trading |
| `get_fund_net_value` | Get fund net value (NAV) history. | Non-Trading |
| `get_fund_files` | Get fund files/documents. | Non-Trading |
| `get_financial_alert` | Get financial alert (next report estimates vs last year). | Non-Trading |
| `get_financial_indicators` | Get financial indicators (key ratios/metrics) for a stock. | Non-Trading |
| `get_income_statement` | Get income statement for a stock across periods. | Non-Trading |
| `get_balance_sheet` | Get balance sheet for a stock across periods. | Non-Trading |
| `get_cash_flow` | Get cash flow statement for a stock across periods. | Non-Trading |
| `get_market_sectors` | Get market sector overview ranking. | Non-Trading |
| `get_market_sectors_detail` | Get stock list and statistics for a specific market sector. | Non-Trading |
| `get_high_dividend` | Get high dividend stocks ranking. | Non-Trading |
| `get_52_week_high_low` | Get 52-week high/low stocks ranking. | Non-Trading |
| `get_market_sentiment` | Get the US market fear & greed sentiment index with historical comparison points. | Non-Trading |
| `get_stock_unusual_activities` | Get recent unusual activity alerts (volume surge, price spike) for US stocks. | Non-Trading |
| `get_institution_identifier` | Search US institutional investors by name or SEC CIK. | Non-Trading |
| `get_institution_holdings` | Get a US institution's 13F holdings. | Non-Trading |
| `get_institution_holding_changes` | Get a US institution's holding changes by position type (OPEN/CLOSE/CHANGE). | Non-Trading |
| `get_insider_transactions` | Get insider transaction records for a US stock (optional BUY/SELL filter). | Non-Trading |
| `get_insider_holdings` | Get insider ownership statistics overview for a US stock. | Non-Trading |
| `get_macroeconomic_calendar` | Get the US macroeconomic event calendar for a date range. | Non-Trading |
| `get_option_contracts` | List US-listed option contracts by underlying, expiry, strike, type, etc. | Non-Trading |
| `get_option_snapshot` | Get real-time option snapshots (up to 20 symbols). Requires option market data subscription. | Non-Trading |
| `get_option_bars` | Get option historical OHLCV bars. Requires option market data subscription. | Non-Trading |
| `get_option_tick` | Get option tick-by-tick trade data. Requires option market data subscription. | Non-Trading |
| `search_news` | Search US market news by keyword. | Non-Trading |
| `get_news_detail` | Get the full content of a US market news article by ID. | Non-Trading |
| `get_stock_news` | Get news related to a US stock, with optional sentiment filter. | Non-Trading |
| `get_community_hot_stocks` | List stocks ranked by community activity. | Non-Trading |
| `get_community_posts` | List community posts for a symbol, with optional keyword search and pagination. | Non-Trading |
| `get_community_post_detail` | Get detailed information for a community post, including attached tickers. | Non-Trading |
| `get_my_community_posts` | List community posts created by the current user. | Non-Trading |
| `create_community_post` | Create a plain-text community post, optionally tagged with a symbol (publishes under your account). | Non-Trading |
| `create_community_comment` | Create a plain-text comment on a community post (publishes under your account). | Non-Trading |
| `place_algo_instruction` | Create an algo order instruction (requires confirmation in Webull APP / Desktop). | Trading |
| `place_crypto_instruction` | Create a crypto order instruction (requires confirmation in Webull APP / Desktop). | Trading |
| `place_event_instruction` | Create an event order instruction (requires confirmation in Webull APP / Desktop). | Trading |
| `place_futures_instruction` | Create a futures order instruction (requires confirmation in Webull APP / Desktop). | Trading |
| `place_option_single_instruction` | Create a single-leg option order instruction (requires confirmation in Webull APP / Desktop). | Trading |
| `place_option_strategy_instruction` | Create an option strategy order instruction (requires confirmation in Webull APP / Desktop). | Trading |
| `place_stock_instruction` | Create a stock order instruction (requires confirmation in Webull APP / Desktop). | Trading |
| `revoke_instruction` | Revoke a previously created order instruction. | Trading |
| `get_pending_instruction` | Get pending order instructions awaiting confirmation. | Trading |
| `get_processed_instruction` | Get processed order instructions. | Trading |
| `get_account_authorization` | Get the account's MCP authorization info. | Non-Trading |

---

## How To Use Cloud MCP {#connect-cloud-mcp}

We provided a video to demonstrate how to connect and use Webull Cloud MCP in the AI markets include ChatGPT, Claude, and Grok. For other AI code platforms, we have provided some examples of connections.

### AI Market

You can operate it on [ChatGPT](https://chatgpt.com), [Claude](https://claude.ai/new) and [Grok](https://grok.com).

<video src="https://u1sweb.webullfinance.com/gtms/us/20261009/ed338ba56a8f4ac88461e52ecc51f06a/Agentic-US.mp4" controls width="80%"></video>

### AI Code Platform

#### Codex

Run the following command in your terminal:

```bash
codex mcp add webull --url https://api.webull.com/mcp
```

Then follow the OAuth authorization flow in Codex when prompted.

#### Cursor

Settings → MCP Servers → Add Remote MCP Server, then enter the URL above.

#### Kiro

Open the `mcp.json` by clicking on `Cmd + Shift + P（Mac）` or `Ctrl + Shift + P（Windows）`,Then make the following configurations:

```json
{
  "webull": {
    "url": "https://api.webull.com/mcp",
    "disabled": false,
    "autoApprove": []
  }
}
```

#### Zed

Add the following to your `settings.json` under the `context_servers` key (key name is customizable):

```json
{
  "mcpServers": {
    "webull": {
      "url": "https://api.webull.com/mcp"
    }
  }
}
```

#### Cherry Studio

Settings → MCP Servers → Add, then enter the URL above.

## How To Place Order Using MCP {#place-order-mcp}

You can learn how to use MCP to place orders through this video.

<video src="https://u1sweb.webullfinance.com/gtms/us/20260922/6cf8e0f63540407b8780300356b94a49/Order_Place_US.mp4" controls width="80%"></video>