Finance MCP

Finance MCP

AI アシスタントに、実際の証券口座とその周辺市場への読み取りアクセスを提供する MCP サーバーです。 注文を送信するボタンは、アシスタントではなく、あなたにだけ用意されています。

Webull、Saxo、IBKR、Yahoo Finance、SEC EDGAR、BLS、Federal Reserve、BEA を通じて 38 個のツールを提供するほか、注文を実行する唯一の手段となる Streamlit ダッシュボードも備えています。ツール一覧は、お使いのブローカーで実際に利用できるものに絞り込まれるため、口座によって表示されるのは 36 個または 37 個です。ブローカーがなくても 28 個のツールが利用でき、これは正常に動作している状態であり、インストールの不具合ではありません。

アシスタントは注文の下書きを作成できますが、発注はできません。 下書きはローカルキューに送られます。送信するには、ブローカーによるプレビューと、ダッシュボード上でのあなたのクリックが必要です。この操作経路はツール側には存在しないため、どんなプロンプトでも到達できません。

各ツールは、読者にだけでなくクライアントにもこの情報を宣言します。36 個中 32 個は読み取り専用として注釈され、1 個は破壊的な操作です（cancel_order は、発注済みで未約定の注文を取り消します）。MCP の注釈を尊重するクライアントであれば、価格照会はそのまま通し、市場に届く唯一の呼び出しで処理を止められます。

アカウントでできること、できないこと

見知らぬリポジトリに証券口座の認証情報を求められるのは、ソフトウェアにおける最も大きな信頼上の要求です。そのため、40段落も下ではなく、ここでお答えします。

• ツール側には注文を実行する経路がありません。 制限されているわけでも、保護されているわけでもなく、存在しません。draft_order はローカルキューに書き込みます。注文の送信には、ブローカーのプレビューとダッシュボードでのクリックが必要です。プロンプトからこれにアクセスすることはできません。
• 38個のツールのうち28個はブローカーに一切アクセスしません。 SEC 提出書類、マクロ、インジケーター、オプション計算、決算情報です。認証情報がまったくなくても、この28個を利用できます。機能が制限されたインストールではなく、通常どおり動作するインストールです。
• 3つのアダプターのうち2つは、まだ一度も実行されていません。 Saxo と Interactive Brokers のアダプターは、公開されている API リファレンスに基づいて構築されており、ライブ口座でもペーパー口座でも実行されていません。これらを使うツールの出力には、すべてその旨が記載されます。実際の口座で実行されたことがあるのは Webull だけです。
• ダッシュボードの送信ボタンは Webull 専用です。 MCP ツールはブローカープロトコルを経由しますが、このボタンはまだそうではありません。
• ブローカーが読み取り専用キーを提供している場合は、それを使用してください。 ダッシュボード以外で書き込み権限が必要になることはありません。

32個のファイルにまたがる1,431件のテストがあり、CI はプッシュのたびにそれらを実行します。

これらのテストはすべてネットワークをスタブ化しています。それが正しい方法です。SEC が夜中に 503 を返したせいで失敗するテストスイートは、誰にも読まれなくなります。一方で、そのために2つの不具合がすべてのテストをすり抜けました。8か月前に公開が停止したユーロ圏の系列が最新として報告されていたことと、提出書類を監視する機能がすべてのリクエストに 403 を返しながら正常だと報告していたことです。どちらも確認するには実際のインターネット接続が必要でした。tests/test_live_sources.py はすべての外部ソースに実際に問い合わせ、このツールが応答について正しく報告しているかを確認します。特に、新鮮とマークされた系列が本当に新鮮かを検証します。これはオプトインで、デフォルトではスキップされます。

FINANCE_LIVE_SOURCES=1 pytest tests/test_live_sources.py -v -s

また、週次で CI でも実行されます。誰かが覚えていることに依存するチェックは、いずれ実行されなくなるからです。公開が終了した系列や壊れたスクレイパーは、まさに何週間もかけて静かに発生する障害です。このワークフローは、リポジトリのシークレットとして FRED_API_KEY と SEC_USER_AGENT が設定されるまで動作しません。設定されていない場合は、何も検証していないのに緑のチェックマークを報告するのではなく、ジョブのサマリーにその旨を表示します。

---

オーバーレイ付きのローソク足、出来高パネル、予測コーンです。週末と市場の休場日は折りたたまれるため、空白期間はありません。

---

できること

価格	Webull のライブ OHLCV データを取得し、利用できない場合は Yahoo にフォールバックします。整合性チェックでは、バーの並び順、取引セッション単位での鮮度、OHLC の妥当性を確認します。各価格には、どのバーのデータか、そのバーがどれだけ古いかが示されます。
分析	バージョンを固定した96個のテクニカル指標、POC とバリューエリアを含む出来高プロファイル、Black-Scholes のグリークスとインプライド・ボラティリティ、バックテスト、ATR を考慮したストップに基づくポジションサイジング、ポートフォリオの集中度と相関を提供します。
提出書類	SEC EDGAR のデータを転送するのではなく解析します。取引コードと 10b5-1 のステータスを含む Form 4、項目コード別の 8-K、13F、13D/G、144、NPORT、インライン XBRL に対応します。Form 4 の XML は約6,600トークンになりますが、ツールは代わりに回答を返します。
マクロ	BLS、FRB（FOMC、ドットプロット会合のフラグ付き）、BEA（PCE、GDP）の経済カレンダーを提供します。各行には、発表済みの数値、またはその前回値が記載され、予測値は含まれません。
注文執行	注文の下書き、ブローカーのプレビュー、人による承認を行います。取引前チェックでは、裸のショートをブロックし、通貨ごとの購買余力を検証し、ブローカー独自のルールで拒否される注文を拒否します。

---

必要なもの

OS	Windows、macOS、Linux。デスクトップ通知には各プラットフォーム固有の通知機能（PowerShell、osascript、notify-send）を使用します。通知機能がないマシン（ヘッドレスサーバーなど）では、その旨を明確に報告します。
インストール	uv tool install --with streamlit --with plotly hitl-finance-mcp を実行し、クライアントの接続先を finance-mcp コマンドに設定します。スクリプト形式のインストーラー（install.sh、install.bat）を使うと、設定テンプレート、クライアント登録、ショートカットが追加されます。
Python	3.10 または 3.12。どちらも CI でテストされています。uv は自動的にインストールされます。
ブローカー	任意です。Webull、Saxo、IBKRから選択し、FINANCE_BROKER を設定します。実際の口座で動作確認済みなのは Webull のみです。ブローカーの認証情報がない場合、口座ツールと注文ツールは登録されず、価格情報は Yahoo から取得されます。他の28個のツールは通常どおり動作します。
キー	SEC_USER_AGENT（SEC が提出書類に必要としている連絡先アドレス）と、任意で無料の BLS キーを設定します。

インストールガイド → — 所要時間は15分。その大半は無料 API キーの取得待ちです。

実際の口座に実際の注文を出します。 コンセンサススコアは固定ウェイトのヒューリスティックであり、バックテストではバイ・アンド・ホールドを下回っています。この点は全体を通して明記されています。投資助言ではありません。免責事項の全文とサードパーティーデータの利用条件については、 NOTICE.md をご覧ください。

---

ブローカー

ブローカー	状況
Webull	エンドツーエンドで動作確認済みです。実際の注文を作成、プレビュー、発注し、未約定の状態を確認してからキャンセルしました。
Saxo Bank	未検証です。 Saxo が公開している OpenAPI リファレンスを基に実装されており、同社の API に対して実行されたことはありません。
Interactive Brokers	未検証です。 Client Portal Web API リファレンスを基に実装されており、同 API に対して実行されたことはありません。ローカルの Client Portal Gateway が必要です。

未検証のアダプターは、使用するすべてのツール出力でその旨を示し、ドキュメントで確定していない経路については推測せずに処理を拒否します。

dashboard/broker_protocol.py がインターフェースです。tests/test_broker_conformance.py は、すべてのアダプターに対して同じテストスイートを実行します。FINANCE_BROKER=ibkr を設定すると、プロトコルと MCP ツールが使用するアダプターを選択できます。

どのブローカーで何が使えるか

38 個のツールのうち 28 個はブローカーに依存しません。指標、オプション、SEC 提出書類、インサイダーおよび機関投資家のデータ、決算、マクロデータが該当します。どのブローカーを通じて取引を清算しても同じように使えますが、これらが利用する価格データは、対応する場合、現在はお使いのブローカーから取得します（下記参照）。

8 つは口座および注文のツールで、broker_protocol.py を経由するため、必要な機能を宣言しているアダプターであればどれでも使えます。

ツール	必要な機能
get_account_info get_open_positions get_open_orders	accounts positions open_orders
draft_order preview_order cancel_order	buying_power preview_order cancel_order
calculate_position_size get_portfolio_risk	buying_power positions

設定済みのブローカーが対応できる場合に限り、ツールが登録されます。 FINANCE_BROKER=saxo で起動すると、cancel_order は tools/list に表示されません。Saxo では独自の注文 ID でキャンセルし、こちらの ID からの対応付け方法を公開していないため、キャンセルツールを用意しても、拒否することしかできないからです。使えないツールはリクエストのたびにモデルのコンテキストを消費し、モデルが誤った選択をする可能性も高めます。

同じルールは、ブローカーが設定されていない場合にも適用されます。どのアダプターも遅延して初期化されるため、ツールの一覧表示でソケットが開くことはありません。そのため、.env が空でもブローカーオブジェクトは問題なく作成され、口座ツールを一つも実行できないユーザーにも、8 つすべてが提示されていました。現在はオフラインで認証情報を確認し、認証情報がある場合にのみ登録するため、ブローカーなしのインストールでは、36 個中 8 個が使えない状態ではなく、すべて使える 28 個のツールが表示されます。オフラインでは本当に判断できない場合もあります。IBKR の Client Portal Gateway はブラウザでログインした後にセッションを保持し、トークンを一切必要としません。その場合はツールを登録したままにします。使えるツールを隠してしまうと、なぜ使えないのかを知る手段がなくなるからです。

さらに 2 つのツールは、対応しているブローカーでのみ利用できます。saxo_corporate_actions（配当、株式分割、公開買付け、およびそれらの選択期限に対応。3 社のうち対応しているのは Saxo のみ）と、ibkr_market_scanner（ETF 価格を 11 件取得してローテーションを推測するのではなく、取引所側でスキャンします）。

機能の判定はブローカー名ごとではなく、口座ごとに行います。以下の 3 つの条件がすべてそろう必要があるためです。

capability = what the SDK implements
           ∩ what the regional entity serves
           ∩ what this account is entitled to

Webull だけでも、別々のホストで稼働する 12 の独立した地域エンティティがあり、市場データの利用権もそのうえで口座ごとに購入します。そのため、板情報が 1 段しか返されない場合は、エンドポイントがないのではなく、L1 のサブスクリプションが必要だということです。dashboard/capabilities.py はブローカー × エンティティ × 口座をキーにキャッシュを管理します。プローブによって機能が取り消されることはあっても、新たに機能があると判定されることはありません。また、失敗の理由ではなく、呼び出しで何が起きたかを記録します。エラーメッセージから原因を推測した結果、以前このファイルはパラメーターの誤りを地域の問題だと誤認していました。

マクロ指標の発表

CPI は米東部時間の 08:30:00 に発表されます。カレンダーに表示されるのは、すでに発表された結果か、その前回の結果であり、予測値ではありません。コンセンサスを配信するフィードはここにはありません。市場予想はライセンスが必要な情報であり、前回の値との差を「サプライズ」と呼ぶことはできません。

発表予定時刻が近づくと、マクロデータのキャッシュ有効期間は 6 時間から 3 秒に短縮されるため、問い合わせるたびに利用できる最新の情報が返されます。FINANCE_MACRO_WATCH=1 を設定すると、バックグラウンドスレッドも発表と同時にデータを取得するため、発表された時点で結果をすでに取得しています。

ただし、リクエストを連続して大量に送っても意味はありません。BLS は 10 秒あたり 50 リクエストと公表しており、短い間隔で取得する場合も 10 リクエストにとどめています。ポーリング頻度を上げても、BLS の発表が早まることはありません。外部イベントの発生を待っているのであって、処理量の問題ではないため、同じリクエストを発表時刻にまとめて送っても、すべて同じ古いデータが返されます。

価格データはブローカーから取得します

fetch_data はまず設定済みのブローカーを試し、次に Yahoo を試します。そのため、Saxo ユーザーは Saxo の /chart/v1/charts を、IBKR ユーザーは /iserver/marketdata/history を利用します。対象はアカウント関連ツールだけでなく、サーバー内のすべての価格データです。これまでは、Saxo や IBKR の認証情報を設定しても、価格データ全体が公開フォールバックを使い続けていました。ツール自体は引き続き動作していたため、そのことには気づけませんでした。フォールバックが使われると、必ずその旨が通知されます。

どちらのブローカーのデータフィードも、返却前に昇順に並べ替えます。Webull は新しい順で返していましたが、並べ替えが行われていなかったため、すべての指標が逆順の時系列データに対して実行され、セクターのヒートマップでは最もパフォーマンスの悪い銘柄がリーダーとして表示されていました。同じ間違いを繰り返すべきではありません。

contract_rules() は実際のティックサイズとロットサイズを取得し、rule_violations() はそれらが渡された場合に使用します。これにより、注文プレビューでは問題なく価格が表示されるのに、発注時に拒否される問題を検出できます。

ダッシュボードの送信ボタンは、引き続き Webull 専用です。 MCP ツールはプロトコル経由で処理されますが、Streamlit の承認・送信パスはまだ対応していません。これを変更するには、実運用で試された唯一のコードパスに、誰も実行したことのない2つのアダプターを組み込む必要があります。まず検証が必要です。それがHELP-WANTED.mdで協力を求めている理由です。

IBKR は Client Portal の Web API であり、通常のリクエスト／レスポンス形式の JSON を使用します。TWS のソケット API ではありません。この違いがあるため、これは全面的な書き直しではなく、アダプターとして実装されています。また、プロトコルにはまだなかったブローカー固有の動作が1つあります。IBKR は発注に対して注文の代わりに警告を返すことがあり、送信前にそれぞれの確認が必要です。クライアントライブラリでは通常、定型応答のテーブルを使ってこれらに応答します。このツールでは、注文を承認した本人に警告を提示します。それこそが、このツールの目的です。

協力をお願いします → — Saxo のシミュレーショントークン、または IBKR のペーパー口座を使った1時間の作業で、検証の不足を解消できます。検証用スクリプトは読み取り専用で、発注することはありません。

---

あらゆる MCP クライアントで動作します

サーバーは特定のアシスタントに依存しません。stdio 経由で MCP を話すため、MCP に対応するあらゆるものから実行できます。インストーラーはマシン上で検出したすべてのクライアントに登録します。手動で設定する場合は、そのクライアントの MCP 設定に次の内容を追加してください。

{
  "mcpServers": {
    "finance": {
      "command": "finance-mcp",
      "args": []
    }
  }
}

クライアント	設定場所
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	claude mcp add finance -- finance-mcp
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code	.vscode/mcp.json、またはユーザーレベルの MCP 設定
その他	各クライアントで MCP 設定と呼ばれる場所。上記の JSON が標準形式です

ダッシュボードは独立した Streamlit アプリであり、どのクライアントを使っているかには関係ありません。注文の承認は、いずれの場合もダッシュボードで行います。

---

マクロカレンダーとリアルタイムの開示書類

ブローカーのフィードに加えて、4つの公開ソースを利用できるため、Claude は価格そのものだけでなく、価格を動かすイベントも確認できます。

ツール	提供内容
get_economic_calendar	3つのソースから取得した米国の予定イベントです。BLS（CPI、PPI、NFP、JOLTS）、連邦準備制度（FOMC の決定。ドットプロットを伴う場合はその旨を表示）、BEA（PCE、GDP、貿易）が含まれます。各行には、発表済みの場合は実績値、未発表の場合は前回の実績値が含まれます。
get_updates	指定したタイムスタンプ以降の変更内容です。新しい SEC 開示書類、発表済みのマクロ指標、大幅な価格変動を確認できます。すべてを再取得せずに「何か新しい情報はありますか？」に回答できます。
get_macro_data	CPI、コア CPI、失業率、雇用者数、PPI、賃金の過去データと前月比・前年比の変化です。source="markets" では、FRED、ECB、イングランド銀行の政策金利、イールドカーブ、金融環境を取得できます。
get_edgar_filings	3つのモードで SEC 開示書類を取得します。特定企業の開示書類、全登録者のライブフィード、または開示書類本文の全文検索です。
get_insider_activity	解析済みの Form 3/4/5 です。誰が、いくらで取引したか、売却が Rule 10b5-1 プランに基づくものかどうか、および新規保有ポジションを確認できます。forms="144" では、取引前に提出された売却予定情報と、プランの採用日を取得できます。
read_filing	フォームに応じて情報を取得します。DEF 14A から役員報酬、13D/13G の表紙、8-K からプレスリリース、10-K から指定した項目（リスク要因、MD&A）、またはテキスト検索に対応しています。
get_institutional_holdings	最新の 13F-HR ポートフォリオです。複数の運用者行にまたがるポジションを統合します。source="NPORT" では、13F に含まれない債券やデリバティブを含む、登録ファンドの月次ポートフォリオを取得できます。

開示書類は転送するのではなく、解析します。 アナリストが開示書類から知りたい情報の多くは、すでに機械可読なフィールドになっています。「あの売却は事前に予定されていたのか？」という情報は、Form 4 の XML にある <aff10b5One> というブール値です。そのため、サーバーは文書を渡すのではなく、情報を抽出して回答します。Form 4 の XML は生データで約6,600トークン、10-K は約610,000トークンあり、20万トークンのコンテキストウィンドウの3倍に相当します。また、get_insider_activity は、実際の意思決定（コード P/S）と、報酬に関する処理（付与、オプション行使、納税のための株式控除）を区別します。こうした処理は、よく「インサイダーが X ドル分を売却」と誤って報じられます。

遅延について。 EDGAR の受理タイムスタンプは秒単位で正確なため、決算の 8-K（項目 2.02）は受理され次第確認できます。実際に生じる遅延は、フィードではなく、ポーリング間隔によるものです。get_earnings は同じ項目コードを使って、実際に発表された四半期を確認し、Yahoo が推定している今後の発表日を明示します。Yahoo は未確定の日付を期間として、確定した日付を単一の日として公開するため、書式化すると両者は区別できなくなります。

コンセンサスはなく、その旨を明示します。 市場予想はライセンス対象の情報であり、無料で利用できるソースはありません。そのため、カレンダーのすべての比較対象は前回の実績値であり、そのようにラベル付けされています。前回値との比較で測った「サプライズ」は、サプライズではありません。市場が取引するのは予想との差であり、ここで入手できないのはまさに予想です。

レート制限とクォータの処理。 BLS は未登録の場合、1日あたり25回の API クエリを許可しています。発表スケジュールのページは通常のウェブ取得であり、意図的にこのクォータを消費しません。結果はキャッシュされるため（マクロ系列は6時間、スケジュールは24時間、開示書類は2分）、カレンダーを再度呼び出してもコストはかかりません。SEC の毎秒10リクエストの上限は、クライアント側で適用されます。

正規化。 提出者名や発表テキストは、さまざまな文字体系や数値表記で提供されます。専用レイヤーが Unicode を正規形に統一し、分解されないラテン文字の合字（Ærø → AEro。r にはなりません）を展開し、ASCII 以外の数字を変換したうえで、米国、欧州、スイス、インド式の数値表記を解析します。(1,234.56) のような会計表記の負数も対象です。

BLS キーの取得（任意、無料、約 2 分）

未登録の場合、API クエリは 1 日あたり 25 件までに制限されます。上限を 500 件に引き上げるには、次の手順を実行してください。

1. data.bls.gov/registrationEngine で登録します。キーは返信メールで届きます。
2. .env に BLS_API_KEY=<your key> を追加し、サーバーを再起動します。
3. validate_bls_key ツールを実行し、キーが受け付けられたことを確認します。

最後の手順は重要です。キーを入力し間違えてもエラーにはならず、気付かないうちに 1 日あたり 25 件の枠に戻ってしまいます。その結果、数日後に割り当て上限に達して初めて問題が表面化します。登録済みの場合は、取得可能な履歴が 10 年から 20 年に延び、BLS が独自に計算した変化率も返されます。サーバーは自身の計算結果を BLS の数値と照合します。

いつでも get_data_sources を使って、各データソースの設定と残りの割り当てを確認できます。

---

協力者募集

誰かの 1 時間が、私の 1 日分以上の価値になる作業が 3 つあります。

• Saxo アダプターの検証。 Saxo が公開しているリファレンスに基づいて作成しましたが、同社の API に対して実行したことはありません。24 時間有効なシミュレーショントークンは無料で、承認も不要です。tests/verify_saxo.py を実行すれば、注文を発注せずに未解決の 6 つの疑問に答えられます。
• IBKR アダプターの検証。 状況は同じですが、ペーパー口座で十分です。Client Portal Gateway を起動し、ブラウザーからログインして、python -m tests.verify_ibkr を実行してください。何も送信せず、読み取りのみを行い、IBKR 独自の拘束力のない whatif を呼び出します。→ HELP-WANTED.md
• クリーンな環境へのインストール。 install.bat と install.sh は、ユニットテストとコードの確認は行っていますが、新規 OS での検証は行っていません。新規ユーザーが最初に触れる部分が、ここで最も検証不足です。

ほかにも対応を歓迎します。IG Markets（REST、Saxo と似た構造）です。 dashboard/broker_protocol.py がインターフェースです。 tests/test_broker_conformance.py は、このインターフェースを実装するあらゆるものに対して実行できます。

---

数値の出所

データの信頼度は一様ではありません。各ツールでは、データの種類を明示しています。

分類	出典	検証
価格とバー	Webull OpenAPI、フォールバックとして Yahoo	完全性ゲート：並び順、取引時間帯に基づく鮮度、OHLC の妥当性
提出済み財務情報	SEC EDGAR XBRL	権威ある情報源。提出書類そのもので、書式と提出日が記載されています
マクロ経済データ	BLS	公式系列。登録済み枠では、MoM／YoY を BLS 独自の数値と照合します
サードパーティのファンダメンタルズ	Yahoo	比較可能な数値がある場合は XBRL の提出書類と照合し、相違があれば報告します
コンセンサススコア	ここで計算	固定ウェイトのヒューリスティックであることを明示しています。バックテストではバイ・アンド・ホールドを下回りました

get_company_financials は提出書類に記載された数値を直接返します。Yahoo と提出書類の数値が一致しない場合は、提出書類の数値を優先し、ツールでその旨を伝えます。

IV ランクは、無料で権威ある情報源から取得できない唯一の指標です。インプライド・ボラティリティの履歴を公開しているフィードはありません。そうした事実を隠すのではなく、このサーバーはオプションが照会されるたびに、シンボルごとに 1 日 1 件の ATM IV 観測値を記録します。対象シンボルの履歴が 30 日分たまると、真の IV ランクを報告します。それまでは、実現ボラティリティを使った代替値であることを明記し、あと何件の観測値が必要かを表示します。

---

データの整合性

市場データはすべての基盤となるため、信頼するのではなく検証します。どちらのソースから取得した価格データのフレームも、ツールに渡される前に共通のゲートを通過します。

• バーの順序を保証します。 Webull API はバーを新しい順に返します。フレームを昇順に並べ替え、不変条件をアサートするため、.iloc[-1] は常に最新のバーを指します。(これを行わないと、ツールは期間内で最も古いバーを現在価格として報告し、時間を逆順にした系列ですべてのインジケーターを計算してしまいます。)
• 鮮度は取引セッションを基準に測定します。 組み込みの NYSE カレンダーを使用します。休場日を含む週末と障害を区別できない暦日では測定しません。
• 妥当性チェックにより、NaN の価格や実現不可能な OHLC バーを除外します。
• 失敗はテキストではなくエラーです。 ツールはコンテンツとして "Error: ..." を返すのではなく、実際の MCP エラーを発生させるため、失敗が結果と誤認されることはありません。
• データソースの切り替えを通知します。 Webull のフィードに問題があり、リクエストを Yahoo が処理した場合、影響を受けるすべてのツールがその旨を伝えます。

pytest でテストスイートを実行します。完全にオフラインで動作するため、認証情報もネットワークも注文も必要ありません。

---

インストール

方法 A — インストーラー（Windows、Python 不要）

1. このパッケージを任意の場所に解凍します（例：デスクトップ）。
2. install.bat をダブルクリックします。
3. uv Python エンジンがない場合はインストールし、サーバーを %APPDATA%\Claude\claude_desktop_config.json に finance という名前で登録し、 .env のテンプレートを作成して、Finance MCP Dashboard のショートカットを デスクトップに追加します。
4. .env に必要事項を入力します（認証を参照）。
5. Claude Desktop を再起動します。 サーバーは起動時にのみ読み込まれます。

WEBULL_APP_KEY または SEC_USER_AGENT がプレースホルダーのままの場合、インストーラーは ACTION NEEDED ブロックを表示するため、設定が不完全なインストールを完了したように見せることはありません。

uv 以外はシステム全体にインストールされません。依存関係はサーバーまたはダッシュボードの初回起動時に キャッシュへ解決されるため、初回の起動はそれ以降より時間がかかります。

Path B — リポジトリをクローンする

インストーラーもショートカットもありません。2 つのエントリーポイントを自分で設定します。

git clone <repo> && cd finance-mcp
uv venv && uv pip install -e ".[dev,dashboard]"
cp .env.example .env      # then edit it — see Authentication below

MCP サーバー（Claude が接続するもの）を、Windows では %APPDATA%\Claude\claude_desktop_config.json に、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json に追加し、 Claude Desktop を再起動します。

{
  "mcpServers": {
    "finance": {
      "command": "uv",
      "args": ["run", "--with", "pandas", "--with", "numpy", "--with", "fastmcp",
               "--with", "yfinance", "--with", "tabulate", "--with", "lxml",
               "--with", "html5lib", "--with", "webull-openapi-python-sdk",
               "/absolute/path/to/finance_mcp.py"]
    }
  }
}

絶対パスを使用し、Windows でもスラッシュを使ってください。Claude Code のユーザーは、代わりに claude mcp add finance -- uv run /absolute/path/to/finance_mcp.py を実行できます。

ダッシュボード（画面で見るもの）を実行します。リポジトリのルートから実行してください。 dashboard/webull_client.py はマーケットデータクライアントと、署名付きリクエストの共通処理を担います。 dashboard/broker.py は取引に関する機能（口座、購買余力、ポジション、注文のライフサイクル）を担います。 障害の発生の仕方が異なるため、両者は分離されています。価格フィードではフォールバックに切り替えてその旨を表示しますが、注文処理では代替せず、リクエストを拒否する必要があります。 dashboard/barcache.py は、MCP サーバーとダッシュボードで共有する、検証済みのバー・フレームを保存する小規模なオンディスクキャッシュです。キャッシュがヒットするとダウンロードを省略しますが、整合性チェックは省略しません。FINMCP_BAR_CACHE=0 で無効にできます。

dashboard/ — app.py は作業ディレクトリを基準に兄弟モジュールと .streamlit/config.toml を解決するため、別の場所から起動するとテーマが適用されません。

streamlit run dashboard/app.py            # inside the venv
# or, without activating anything:
uv run --with streamlit --with plotly --with pandas --with numpy \
       --with yfinance --with lxml --with html5lib --with tabulate \
       --with webull-openapi-python-sdk streamlit run dashboard/app.py

http://localhost:8501 で開きます。ポートを変更するには --server.port 8899 を追加します。

ループバックインターフェースのみにバインドします。 Streamlit では、デフォルトで server.address が未設定です。未設定は localhost を意味せず、すべてのインターフェースでリッスンします。このアプリの場合、同じネットワーク上の誰もが、稼働中の証券口座、そのポジション、実行可能な注文送信ボタンにアクセスできてしまいます。.streamlit/config.toml では 127.0.0.1 を指定しており、finance-mcp-dashboard も、インストール先にそのファイルがない場合に備えて同じフラグを渡します。これはデフォルト設定であり、固定ではありません。別の場所で公開する意図が本当にある場合は、自分で --server.address を指定してください。その場合は、認証機能がないため、前段に何らかの保護手段を置いてください。

アラートマネージャー（任意、Windows のトースト通知）。ダッシュボードはこれをバックグラウンドスレッドで自動起動します。単独で実行するには、次のコマンドを使います。

python -m dashboard.alert_manager

インストールを検証する — pytest を実行すると、認証情報もネットワーク接続も不要で、テストスイート全体をオフラインで実行できます。

pytest -q

次に、Claude に get_data_sources を実行するよう依頼します。口座にアクセスすることなく、設定済みの認証情報、接続可能なフィード、残りのクォータを確認できます。check_connection では、Webull セッションを個別に確認できます。

---

認証

1. このフォルダー内に新しく生成された .env ファイルを開きます。
2. Webull の WEBULL_APP_KEY と WEBULL_APP_SECRET を貼り付けます。
3. ファイルを保存します。

.env と conf/token.txt は gitignore の対象です。また、SDK のログは書き込み時に認証情報が伏せられます。Webull SDK は完全な署名付きリクエスト（キー、HMAC 署名、アクセストークン）を ERROR レベルで出力するため、これを行わないと、通常のレート制限応答によって認証情報がそのままディスクに書き込まれるおそれがあります。

オプション設定

変数	デフォルト	用途
WEBULL_ENVIRONMENT	prod	prod がデフォルトで、実際の口座で取引します。読み取りがこのツールの用途であり、ダッシュボードで承認しない限り注文が実行されることはありません。paper は「ライブデータ、シミュレーション注文」ではありません。クライアント全体を Webull のサンドボックスに接続し直すため、株価情報も含めてすべてが切り替わります。サンドボックスには独自のアプリレジストリがあるため、本番環境のキーを使用すると 401 が返され、何も機能しません。承認フローのリハーサルに限り、WEBULL_PAPER_APP_KEY／SECRET と併せて使用してください。paper（別名 uat、sandbox、simulated）を指定すると、すべての呼び出しがご利用の地域の Webull シミュレーション環境に送られ、ドラフト、プレビュー、承認、送信という承認フロー全体を、リスクなしでリハーサルできます。ダッシュボードには、ロゴの横と「Execution」タブに LIVE または PAPER と表示されます。ご利用の地域のサンドボックスホストが公開されていない場合、クライアントは本番環境にフォールバックせず、起動を拒否します。
WEBULL_PAPER_APP_KEY / WEBULL_PAPER_APP_SECRET	—	オプション。ペーパーモード専用です。Webull のサンドボックスは独立したデプロイ環境であり、独自のアプリレジストリを備えているため、本番環境のキーで認証すると 401 UNAUTHORIZED が返されます。これは実環境で確認済みです。サンドボックスアプリを登録してこれらを設定してください。未設定の場合、ペーパーモードは本番環境用のキーのペアにフォールバックするため、401 が返されます。
WEBULL_ACCOUNT_ID	(未設定)	特定の口座を指定します。ログインに複数の口座が紐づいている場合は必須です。誤った口座で誤って取引することがないよう、サーバーは推測せずに処理を拒否します。
WEBULL_MIN_REQUEST_INTERVAL	0.25	Webull API 呼び出しの間隔（秒）。リクエスト間隔を調整することで、一覧を一括スキャンするツール（セクターのヒートマップ、ウォッチリストのスキャン）がレート制限にかからないようにします。
WEBULL_MAX_RETRIES	3	レート制限された呼び出しを諦め、フォールバックするまでの試行回数です。
WEBULL_RETRY_BACKOFF	0.75	HTTP 429 に対する指数バックオフの基準秒数です。
WEBULL_REGION_ID	th	Webull の地域です。Yahoo の .BK ティッカーへのフォールバックの可否も決まります。
SEC_USER_AGENT	(未設定)	EDGAR ツールには必須です。 SEC の公平なアクセスに関するポリシーでは、実際の連絡先住所を含む説明的な User-Agent が求められます。例：Your Name ([email protected])。これが設定されていない場合、IP 禁止のリスクがある匿名リクエストを送信するのではなく、ローカルでリクエストを拒否します。
BLS_API_KEY	(未設定)	オプションです。キーなしでも BLS は 1 日 25 クエリまで利用できます。無料キーを取得すると 1 日 500 クエリまで利用でき、より長期間の履歴にもアクセスできます。

---

使用方法

アシスタントから

MCP クライアントを再起動してサーバーを読み込ませてから、必要なことを尋ねてください。 「NVDA の日足チャートはどうですか？」、「今週の経済カレンダーには何が予定されていますか？」、「AAPL を 10 株、300 で指値買いするドラフトを作成して。」。最後の指示はキューにドラフトを書き込み、そこで停止します。

ダッシュボードで

Finance MCP Dashboard のショートカットをダブルクリックするか、リポジトリのルートから streamlit run dashboard/app.py を実行します。タブは9つあります。

タブ	用途
Charts	オーバーレイ、出来高パネル、予測コーンを含むローソク足チャートです。ドラッグでパン、スクロールでズーム、ダブルクリックでリセットできます。単一の軸をドラッグすると、その軸だけをスケールできます。週末と市場休場日は折りたたまれるため、空白の期間はありません。
Backtest	読み込んだ期間に適応型コンセンサスルールを適用し、CAGR、シャープレシオ、最大ドローダウン、プロフィットファクター、エクスポージャーを表示します。
Journal	log_journal_entry を通じて Claude が記録した投資仮説を表示します。記録された価格が市場価格から離れている場合は、乖離の警告が表示されます。
Signals	コンセンサススコアの根拠となる4つの指標の判定と、それらの算出に使用されたレジーム加重マトリクスを表示します。
Execution	注文承認デスクです。詳細は以下をご覧ください。
Portfolio	ブローカーから直接取得した現在の残高、購買余力、損益付きのオープンポジションに加え、時間経過に伴う価値のチャートを表示します。ポジションの評価額にはそれぞれの通貨が表示されます。THB口座内のUSD建て保有資産が口座の基準通貨と合算されることはありません。
Events	経済カレンダー（BLS、FOMC、BEA）と各項目の実績値または前回値、ウォッチリスト銘柄のSEC提出書類、提出書類と価格変動に関する「前回からの変化」の差分を表示します。
Alerts	価格、RSI、MACDクロスのアラートです。マネージャーがWindows通知を表示し、トリガーとなったバーを記録します。
Data	読み込んだ期間について、計算されたすべての指標列を新しい順に表示します。

Events タブ：各項目の実績値または前回値を含む経済カレンダー、確定・係争中・推定として示された決算日、ホバーするとプレビューが表示されるウォッチリストの提出書類。

Execution タブ — 市場への唯一の経路です。まずブローカーでプレビューし、その後に承認します。

右上の DISPLAY では、ビジュアルテーマ（デフォルトの Terminal、Research、Slate）、チャートのオーバーレイ配色、行の密度を切り替えられます。

注文を送信できるのは Execution タブだけです。 送信は意図的に2段階になっています。1 — Webull でプレビューでは、ブローカーに注文の価格を提示させます（拘束力はありません）。その後にのみ、2 — 承認して送信が有効になります。ブローカーがプレビューできない注文は送信されません。また、送信に失敗した場合、下書きは保留のままとなり、約定済みにはなりません。

3. Claude にできること、できないこと

価格、提出書類、マクロ経済系列、残高、ポジションを読み取る	はい
ローカルのJSONファイルに注文の下書きを作成し、ブローカーでプレビューする	はい
注文を送信する	いいえ — 送信ボタンはダッシュボードにのみ存在し、ブローカーでのプレビュー後にのみ使用できます

Claude に注文送信権限を付与する設定フラグはありません。この手順から人間を外すには、ソースを編集する必要があります。

---

免責事項：これは、教育および実験的な定量調査を目的としたオープンソースプロジェクトです。アルゴリズム取引には重大な金銭的リスクが伴います。

mcp-name: io.github.Blahaj-gif/hitl-finance-mcp