Webull MCP Server

An MCP サーバーで、公式の Webull OpenAPI (webull-openapi-python-sdk) を、MCP クライアント(Claude Code、Claude Desktop、その他任意のクライアント)が呼び出せるツールとして公開します。口座残高、保有ポジション、注文、株価、過去のバー、米国オプションの市場データを読み取ることができます。オプションで、実際の株式注文の発注・キャンセルもできます。

⚠️ インストールに失敗する前に必ずお読みください

非公式なものです。 このプロジェクトは Webull とは提携しておらず、Webull から承認・支援を受けているものでもありません。これはサードパーティクライアントとして Webull の OpenAPI を呼び出すものであり、自己責任で利用してください。API は予告なく変更されたり動作しなくなったりする可能性があります。ここで提供される何かが動き続けることを保証するものはありません。

投資アドバイスではありません。 これは単なる配管に他ならず、戦略ではありません。何を買うべきか、何を売るべきかについての判断を行うものではありませんまた。あなたの口座から発注されるすべての注文と、それらがあなたにもたらすコストに対して、あなた以外の誰も責任を負いません。

売買はデフォルトで無効になっており、ペーパーモードもありません。 注文ツールは、WEBULL_ENABLE_TRADING=true を明示的に設定しない限り、MCP クライアントにすら 登録されません。Webull には ペーパートレード用エンドポイントは一切ないため、有効にした場合、このサーバーが発注する全ての注文はライブ・本物・実際の口座で行われます。 ライブ取引を有効にする もご覧ください。

あなたの認証情報はあなたのマシンの上で維持されます。 App Key と Secret は、ローカルの .env ファイル(gitignored)の中だけに存在します。それらは Webull の API にのみ何かを送信し、モデルや他社に対して送信されることは一切ありません。

ツ

読み取り専用(常時有効)

オプションツールは、OCC フォーマットのシンボル(AAPL260619C00285000 — <ROOT><YYMMDD><C|P><strike × 1000, 8 digits>)を採用しています。Webull にはチェーン一覧のエンドポイントはないので、既知の行使価格と満了日から候補シンボルを組み立て、直接参照してください。1コール最大20件です。

ライブ取引 (ゲート付き、デフォルトでオフ)

WEBULL_ENABLE_TRADING=true のときだけ登録されます。

サポートされる注文タイプ: MARKET, LIMIT, STOP_LOSS, STOP_LOSS_LIMIT; DAYまたはGTC。オプションで時間外のルーティングも可能。

Example Session例

MCP クライアントから実際にあるように使った場合の様子を示します。以下は参考です — お使いの口座に読み替えてください。

> How's my account doing, and what's the SMCI Jan 250 call worth?

● get_account_balance()
  ⎿ {
      "account_id": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
      "net_liquidation": "18432.55",
      "cash_balance": "6120.18",
      "buying_power": "12240.36"
    }

● get_positions()
  ⎿ [
      { "symbol": "INTC", "quantity": "40",  "cost_price": "127.54",
        "last_price": "131.02", "unrealized_pnl": "139.20" },
      { "symbol": "IWM",  "quantity": "15",  "cost_price": "241.88",
        "last_price": "238.15", "unrealized_pnl": "-55.95" }
    ]

● get_option_quote(symbols: "SMCI260116C00250000")
  ⎿ [
      { "symbol": "SMCI260116C00250000",
        "bid": "12.40", "ask": "12.85", "volume": "1843",
        "open_interest": "9021", "imp_vol": "0.5412",
        "delta": "0.4187", "gamma": "0.0092", "theta": "-0.1734",
        "vega": "0.2815", "rho": "0.0946" }
    ]

Net liq is $18,432.55 with $12,240 buying power. INTC is up $139 and IWM
is down $56. The SMCI 250 call is $12.40 × $12.85 — 0.42 delta, 54% IV,
and theta is costing you $17/day per contract.

ここにあるのは読み取り専用ツールについてです。place_order は取引を有効にしない限り一切利用できません — ライブ取引を有効にする を参照。

Setup

1. Webull API の資格情報を取得する

1. Webull Developer Portal にアクセスし、サーバーをアクセスさせる Webull アカウントでサインインします。

2. OpenAPI アクセスを申請し、アプリを作成してください。承認は即座ではありません — Webull によるレビューがあります。

3. 発行されたアプリキーと秘密のように App Key と App Secret をコピーします。

あなたのアカウントは、あなたの地域で OpenAPI が有効にしてください。リアルタイムのマーケットデータは、アカウントにマーケットデータの資格が必要な場合があります。ない場合は、引用が遅延するかもしれません。

2. インストール

git clone https://github.com/<your-username>/webull-mcp.git
cd webull-mcp

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Python 3.10 以上が必要です。

3. 設定する

cp .env.example .env

.env を編集し、資格情報を記入します:

WEBULL_APP_KEY=your_app_key_here
WEBULL_APP_SECRET=your_app_secret_here

# One of: us, hk, jp, sg, th, au, my, uk
WEBULL_REGION=us

# Optional. If set, account tools use this account when you omit account_id.
# Leave blank to auto-resolve the first account from list_accounts.
WEBULL_DEFAULT_ACCOUNT_ID=

# Leave this false unless you have read the trading section below.
WEBULL_ENABLE_TRADING=false

.env は gitignored です。コミットしたり、その内容をどこかへ[ペースト]しない。

4. MCP クライアントに登録する

.mcp.json を編集して、プレースホルダーのパスを自分のクローンの絶対的なものに置き換えます:

{
  "mcpServers": {
    "webull": {
      "command": "/absolute/path/to/webull-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/webull-mcp/src/server.py"]
    }
  }
}

For Claude Code, also drop .mcp.json into a project directory where it will be detected automatically, or register it explicitly:

claude mcp add webull -- /absolute/path/to/webull-mcp/.venv/bin/python /absolute/path/to/webull-mcp/src/server.py

クライアントを再起動します。サーバーが正常に起動したことを確認する:

.venv/bin/python src/server.py

It should start and wait on stdio — output nothing is expected. Ctrl-C で終了します。

最初の呼び出しでアカウントに触れると、SDK は2FAハンドシェイクを行い、conf/ 下にトークンをキャッシュします。そのディレクトリは gitignore されています。

ライブ取引を有効にする（オプション）

これは、すべての注文が実際に実行されることを受け入れた場合のみ行ってください。 サンドボックスもペーパー口座も、誤りを戻しても一切ありません。

1. .env で WEBULL_ENABLE_TRADING=true を設定します — 文字列は厳密に true であることが必要。

2. MCP クライアントを再起動します。インポート方法に応じてツールが登録されるため、再起動が必要です。

3. trading_status ツールで確認します。

2 つの独立したセーフティーレイヤがまだ残ります:

• 登録ゲート — このクロックが未設定または false の場合、place_order、preview_order、cancel_order はモデルには一切公開されません。見えないツールを呼び出すことはできません。

• 確認ゲート — 有効条件でも、confirm=True 付きで呼び出さないと place_order はエラー行けます。まず preview_order を実行します。

無効に再設定するには、フラグを false に戻して再起動します。

注意点と制約

• リージョンはデフォルトで us です。他の会社のために WEBULL_REGION を設定する。

• 注文ツールは株式にのみ対応しています — オプション売買は実装されていません。ここでのオプションサポートは市場データのみです。

• Webull にはオプション・チェーンをリストするエンドポイントがありません。OCC シンボルは自分で組み立ててください。期限切れのcontractは INVALID_SYMBOL を返します。金曜日がマーケットの休日には、金曜日満了 date は木曜日に移行します。

• 統合された、シンボルベースの webull-openapi-python-sdk がベースです。旧式の分離型の webull-python-sdk-* パッケージは、別シリアルメント ID ベースの API を使用します — 両方はインストールしないでください。

• SDK は logs/ 以下にログを書込みます。このログには App Key、2FA トークン、口座 ID が含まれます。 それらには gitignored です。バグレポートに添付する際には、最初に必ず難読化してください。

Contributeings

CONTRIBUTING.md を参照ください。バグ報告と PR を歓迎します。

ライセンス

MIT。