mcp-etf-holdings

mcp-etf-holdings

ETF データ用の MCP サーバーです。ある銘柄を保有しているファンドの確認、手数料の比較、上位保有銘柄の取得を依頼できます。データは Yahoo Finance からリアルタイムで取得します。API キーは不要です。

---

依頼できること

Claude への質問	呼び出すツール
「NVDA を保有している ETF はどれですか？」	find_etfs_holding_stock
「Nvidia に投資するなら、最も経費率が低い ETF はどれですか？」	stock_exposure_summary
「SPY、VOO、QQQ、SCHD を比較してください」	compare_etfs
「SPY の上位保有銘柄は何ですか？」	etf_holdings
「QQQ の経費率と AUM はいくらですか？」	etf_info
「半導体 ETF を探してください」	search_etfs
「Berkshire Hathaway のティッカーは何ですか？」	lookup_symbol

会社名またはティッカーシンボルで検索できます。「Nvidia を保有している ETF はどれですか？」と「NVDA を保有している ETF はどれですか？」は同じように機能します。複数のファンドを一度に尋ねると、比較表が 1 つ返されます。

---

要件

• Python 3.11+
• MCP クライアント：Claude Code、Claude Desktop、VS Code、Cursor、または Antigravity
• uv。手動でインストールせずにサーバーを実行できます

uv をインストールします。

curl -LsSf https://astral.sh/uv/install.sh | sh

---

セットアップ

最初にサーバーをインストールする必要はありません。以下の各設定では、uvx を使って必要に応じてサーバーを起動し、専用の隔離環境で実行します。

代わりに PATH に追加するには、pip install mcp-etf-holdings を実行し、以下の設定で uvx mcp-etf-holdings を通常の mcp-etf-holdings に置き換えてください。

Claude Code

claude mcp add etf-holdings -- uvx mcp-etf-holdings

Claude Desktop

1. 設定ファイルを開きます。

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. サーバーを追加します。

   {
     "mcpServers": {
       "etf-holdings": {
         "command": "uvx",
         "args": ["mcp-etf-holdings"]
       }
     }
   }
   

3. Claude Desktop を終了して、再度開きます。ウィンドウを閉じるだけでは不十分です。

VS Code

1. ワークスペースに .vscode/mcp.json を作成します。グローバル設定を行う場合は、代わりに MCP: Open User Configuration を実行します。

2. サーバーを追加します。VS Code では mcpServers ではなく、servers キーを使用します。

   {
     "servers": {
       "etf-holdings": {
         "type": "stdio",
         "command": "uvx",
         "args": ["mcp-etf-holdings"]
       }
     }
   }
   

3. VS Code を再起動します。

Cursor

Claude Desktop と同じ JSON を使用します。1 つのプロジェクトに設定する場合は .cursor/mcp.json に、すべてのプロジェクトに設定する場合は ~/.cursor/mcp.json に保存します。Cursor を再起動します。

Antigravity

Antigravity は mcp_config.json から mcpServers を読み込みます。すべてのプロジェクトに設定する場合は ~/.gemini/config/mcp_config.json に、1 つのプロジェクトに設定する場合は <workspace>/.agents/mcp_config.json に保存します。

{
  "mcpServers": {
    "etf-holdings": {
      "command": "uvx",
      "args": ["mcp-etf-holdings"]
    }
  }
}

IDE では、エージェントパネルから MCP Servers → Manage MCP Servers → View raw config を選択して開くこともできます。

または、このリポジトリをチェックアウトしてプラグインとしてインストールできます（プラグインは、マニフェストを追加した同じ設定ファイルです。場所は antigravity/etf-holdings です）。

agy plugin install /path/to/mcp-etf-holdings/antigravity/etf-holdings

IDE で使う場合は、そのフォルダーを .agents/plugins/（1 つのワークスペース）または ~/.gemini/config/plugins/（すべてのワークスペース）にコピーします。

オプトインの HTTP トランスポートを使う場合、Antigravity では URL フィールド名に serverUrl を使用します。 {"mcpServers": {"etf-holdings": {"serverUrl": "http://127.0.0.1:8000/mcp"}}}

動作確認

クライアントに次の質問をしてみてください。

• 「NVDA を保有している ETF はどれですか？」 — find_etfs_holding_stock を呼び出します
• 「SPY、QQQ、VTI を比較してください」 — compare_etfs を呼び出し、表を 1 つ返します
• 「Nvidia を保有している ETF はどれですか？」 — 名前を NVDA に解決し、その旨を伝えます

実際の数値が返ってくれば、完了です。

---

プロンプトの例

サーバーに接続しているクライアントに、以下のいずれかをコピーして貼り付けてください。

ファンドを比較する

SPY、VOO、IVV、SPLGを比較してください。すべてS&P 500に連動していますが、最もコストが低いのはどれですか？

QQQ、VGT、XLK、SMHを経費率と5年間のリターンで比較してください。

名前またはティッカーで検索する

Nvidiaを保有しているETFはどれですか？

Berkshire Hathawayのティッカーは何ですか？

Vanguardの米国株式市場全体に投資するファンドを探して、上位保有銘柄を表示してください。

ある銘柄に最も低コストで投資する

Nvidiaに投資するのに最もコストが低いETFはどれですか？

株式を直接購入せずにAMDに投資したいです。どのような選択肢があり、それぞれのコストはいくらですか？

ポートフォリオの重複を確認する

VOO、QQQ、VGTを保有しています。投資先が重複していますか？

SPY、SCHD、DGROのうち、複数に含まれている保有銘柄をすべて表示してください。

テーマ別にファンドを見つける

半導体ETFを探し、規模の大きい3つを比較してください。

配当ETFにはどのようなものがあり、最も利回りが高いのはどれですか？

特定のファンドを調べる

SCHDについて詳しく調査してください。

QQQの集中度はどの程度ですか？上位5銘柄が占める割合はどのくらいですか？

プロンプトテンプレート

サーバーには5つのプロンプトテンプレートが登録されています。Claude DesktopとClaude Codeではスラッシュコマンドとして表示されるため、プロンプトを自分で入力する必要はありません。

テンプレート	引数	機能
etf_deep_dive	ticker	1つのファンドのコスト、規模、リターン、集中度を調査します
compare_funds	tickers	横並びの表とコスト・リターンの比較を表示します
stock_exposure	stock	ある銘柄を保有するETFを、保有比率とコストで順位付けします
portfolio_checkup	tickers	保有するファンド間で重複している銘柄を見つけます
theme_explorer	theme	あるテーマのファンドを見つけ、有力なファンドを比較します

---

ツールリファレンス

複数の行を返すツールは、結果をMarkdownの表として整形します。

etf_info(ticker)

1つのETFのメタデータです。2つ以上のファンドには、compare_etfsを使用してください。

• ticker（string）— ETFのシンボル。例："SPY"

名称、カテゴリー、AUM、経費率、配当利回り、NAV／価格、年初来／3年／5年リターンを返します。

compare_etfs(tickers)

複数のETFを1つの表で比較します。

• tickers（文字列の配列）— 例：["SPY", "QQQ", "VTI", "SCHD"]。大文字・小文字を区別せず、重複は除外されます。1回の呼び出しにつき最大10ファンドです。

ティッカー、名称、カテゴリー、AUM、経費、利回り、年初来、3年、5年を返します。データのないティッカーにも行が追加され、そのティッカーを示す注記が表示されるため、1つの入力ミスで残りの結果が失われることはありません。

etf_holdings(ticker)

ETFの上位保有銘柄とポートフォリオ比率です。

• ticker（string）— ETFのシンボル。例："QQQ"

シンボル、名称、比率（%）を順位付けした表で返します。

find_etfs_holding_stock(stock_ticker, limit, custom_etf_universe)

逆引き検索です。指定した銘柄を開示済みの上位保有銘柄に含むETFを見つけます。

• stock_ticker（string）— "NVDA"のようなティッカー、または"Nvidia"のような企業名です。企業名はティッカーに解決され、使用したティッカーが出力に表示されます。
• limit（int、既定値20）— 最大50です
• custom_etf_universe（JSON文字列、省略可）— 既定のユニバースの代わりに、特定のリストを検索します。例：'["SPY","QQQ","XLK"]'

該当するETFを、対象銘柄の保有比率が高い順に返します。

確認するのは上位保有銘柄のみで、ETFごとにおよそ10～15銘柄です。それ以外の銘柄は表示されません。

stock_exposure_summary(stock, limit)

同じ逆引き検索の結果に、各ファンドのコストと規模を加えます。「この銘柄を保有するのに、最も低コストまたは規模の大きい方法は何か」を調べるのに使用します。

• stock（string）— ティッカーまたは企業名。例："NVDA"または"Nvidia"
• limit（int、既定値10）— 最大25です

ETF、名称、保有比率、順位、経費、AUMを、対象銘柄の保有比率順に返します。

lookup_symbol(query, limit, asset_type)

企業名またはファンド名をティッカーシンボルに解決します。

• query（文字列）— 例："Nvidia" または "Vanguard total stock market"
• limit（整数、デフォルト 10）— 上限は 25 です
• asset_type（文字列、デフォルト "any"）— "any"、"stock"、または "etf"

シンボル、名前、種類、取引所を返します。

search_etfs(query, limit)

名前、テーマ、またはカテゴリーで ETF を検索します。

• query（文字列）— 例："semiconductor" または "dividend"
• limit（整数、デフォルト 10）— 上限は 25 です

一致する ETF のティッカーと名前、取引所を返します。ファンドを検索するのではなく、株式の名前を解決するには、lookup_symbol を使用します。

---

ソースから実行

開発時や、リリースを待たずに実行する場合：

git clone https://github.com/vlearner/mcp-etf-holdings.git
cd mcp-etf-holdings
uv sync

uv を使わない場合：

python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"

リポジトリには、作業ツリーを参照する .vscode/mcp.json が含まれているため、追加設定なしで VS Code にローカルの変更が反映されます。他のクライアントは次の設定を参照してください：

{
  "command": "uv",
  "args": ["run", "--directory", "/absolute/path/to/mcp-etf-holdings", "mcp-etf-holdings"]
}

サーバーが起動することを確認します：

uv run mcp-etf-holdings

標準入力で JSON-RPC を待機し、何も出力せずに停止します。stdio MCP サーバーとしては正常な動作です。

プロトコルを手動で試すには：

npx @modelcontextprotocol/inspector uv run mcp-etf-holdings

HTTP トランスポート（任意）

デフォルトは stdio で、上記のエディター設定はすべてこれを使用します。代わりにストリーム可能な HTTP で配信するには：

uv run mcp-etf-holdings --transport http            # http://127.0.0.1:8000/mcp
uv run mcp-etf-holdings --transport http --port 9000

{ "type": "http", "url": "http://127.0.0.1:8000/mcp" } を使ってクライアントを接続します（VS Code では servers の下に設定します）。MCP_TRANSPORT、MCP_HOST、MCP_PORT で同じオプションを指定できます。

デフォルトではループバックアドレスにバインドされ、認証はありません。--allow-insecure を渡す（または MCP_ALLOW_INSECURE=1 を設定する）場合を除き、別のアドレスへのバインドは拒否されます。使用しているマシンの外部に公開する前に、認証プロキシを前段に配置してください。

Docker で試す

サンプルの Dockerfile は、このチェックアウトからサーバーをビルドします：

docker build -t mcp-etf-holdings .
docker run --rm -e MCP_ALLOW_INSECURE=1 -p 127.0.0.1:8000:8000 mcp-etf-holdings

コンテナーはすべてのインターフェースにバインドするため、MCP_ALLOW_INSECURE=1 が必要です。ポートマッピングの 127.0.0.1: はそのままにしてください。これにより、ネットワーク上の他のマシンからコンテナーにアクセスできなくなります。コンテナー内でサーバーが認証なしの警告をログに出しますが、これは想定どおりです。この設定は機能を試すためのものであり、ホスティング手順ではありません。

テスト

uv run pytest -q

テストスイートは完全にオフラインで実行できます。yf.Ticker と yf.Search はモック化されており、後者は自動適用フィクスチャでモック化されるため、テストが誤って Yahoo に接続することはありません。

カバレッジを確認するには：

uv run pytest -q --cov=mcp_etf_holdings --cov-report=term-missing

ディレクトリ構成

src/mcp_etf_holdings/
  server.py       ← FastMCP entry point, 7 tools
  prompts.py      ← prompt templates, exposed as client slash-commands
  fetcher.py      ← async wrappers around yfinance + 24h TTL cache
  formatting.py   ← markdown tables and shared number formatting
  top_etfs.py     ← ~365 ETF tickers scanned for reverse lookups
  __main__.py     ← enables `python -m mcp_etf_holdings`
tests/            ← pytest suite, fully offline
.vscode/mcp.json  ← VS Code config pointing at the working tree
pyproject.toml

依存関係：mcp（プロトコル SDK）、yfinance（データ）、pandas（保有銘柄のデータフレーム）、httpx（トランスポート）。

---

トラブルシューティング

症状	解決方法
command not found: uvx	uv をインストールし、新しい PATH が反映されるようにエディターを再起動してください。
クライアントにサーバーが表示されない	エディターが MCP 設定を読み込むのは起動時だけです。完全に終了してから再度開いてください。起動エラーについては、クライアントの MCP ログを確認してください。
ターミナルでは動作するが、エディターでは動作しない	GUI アプリはシェルの PATH を引き継がないことがよくあります。uvx の絶対パスを指定してください。パスは which uvx で確認できます。
ツール呼び出しで "No data found" が返される	シンボルが実在することを確認してください。Yahoo のレート制限に達している場合があるため、しばらく待ってから再試行してください。
インストール時に Python のバージョンエラーが発生する	3.11 以降が必要です。python3 --version で確認してください。

---

制限事項

数値を信頼する前に、次の点を把握しておいてください：

• ETF ごとに公開されるのは、上位約 10～15 銘柄のみです。保有銘柄から導き出される情報（逆引き、エクスポージャーの要約、重複チェックなど）は、全体像ではなく最低限の範囲を示します。
• デフォルトの対象は約 365 ファンドです。小規模またはニッチな ETF でしか保有されていない株式は、見つからない場合があります。
• 応答はメモリ内に 24 時間キャッシュされます。ETF_CACHE_TTL_SECONDS で変更できます。
• データは Yahoo Finance からリアルタイムで取得されます。API キーは不要ですが、Yahoo の 利用規約 とレート制限が適用されます。クレジット表記については NOTICE を参照してください。

---

貢献

プルリクエストを歓迎します。特に有用な貢献は、top_etfs.py の ETF 対象範囲を広げることです。対象範囲が広がると、ニッチなセクターや国際市場での逆引き結果が向上します。

大規模な変更を行う場合は、まず issue を作成してください。

---

免責事項

Yahoo Finance、yfinance、またはいかなる金融機関とも提携していません。データは実行時に Yahoo Finance から取得され、利用可能性および同社の利用規約に従います。これは金融アドバイスではありません。