apple-stocks-mcp

🍎 apple-stocks-mcp

macOS 専用の Model Context Protocol（MCP）サーバーです。macOS に付属する株価アプリに保存されているあなた自身のデータ（ウォッチリスト、株価情報、ファンダメンタルズ、アプリがすでにMac 上にキャッシュしている日中チャート）を、AI アシスタントが読み取れるようにします。

**データはすべてローカルに保存され、読み取り専用です。**ホームフォルダー内にある株価アプリのコンテナから、マシン上にすでに存在するファイルを読み取ります。**ネットワークリクエストは一切行わず、外部 API も使用せず、API キーも必要ありません。データが外部に送信されることもありません。**データは株価アプリが最後に同期した内容です。更新するにはアプリを開いてください。

⚠️ **macOS 専用です。**データは macOS の株価アプリのコンテナ内にあるため、このサーバーは Linux や Windows では動作しません。macOS 以外のホストでもサーバー自体は起動しますが、macOS 専用であることと削除方法を丁寧に説明する platform_info ツールのみを公開します。失敗するツールやクラッシュはありません。

---

クイックスタート（30 秒）

Mac で株価アプリを一度開いて（データを作成するため）、次の手順を行います。

Claude Desktop／任意の MCP クライアント — 以下を追加して再起動します。

{ "mcpServers": { "apple-stocks": { "command": "npx", "args": ["-y", "apple-stocks-mcp"] } } }

Claude Code:

claude mcp add apple-stocks -- npx -y apple-stocks-mcp

次に、「今日の Apple 株の動きは？」 と尋ねてください。初回は、クライアントがツールの使用許可を求めます。Yes（または「Yes, and don't ask again」）を選択してください。これで完了です。問題があれば、stocks_doctor を実行するよう依頼してください。修正が必要な箇所を正確に教えてくれます。

---

目次

• 質問できること
• プライバシー
• データの取得元
• ツール · リソース · プロンプト
• 出力例
• 要件
• セットアップ
• FAQ とトラブルシューティング
• 開発とテスト
• 法的事項

---

質問できること

接続したら（セットアップを参照）、アシスタントに次のようなことを尋ねられます。

• 「株価ウォッチリストには何が入っていますか？」
• 「今日の Apple 株の動きは？」
• 「NVDA のファンダメンタルズを見せてください。」
• 「今日、保有株のうち最も値上がりしたのはどれですか？」
• 「ウォッチリスト全体を要約してください。」

---

プライバシー

最も重要なセクションなので、最初に記載しています。

• 読み取り専用です。 サーバーが Stocks アプリのデータを変更、削除、書き込みすることはありません。SQLite キャッシュは sqlite3 の -readonly フラグを付けて開き、ウォッチリストファイルを解析するだけです。書き込みを伴う唯一の操作である add_stock も、ファイルには一切触れません。macOS に Stocks アプリでシンボルを開くよう依頼するだけなので、タップして追加するのは あなた自身 です。
• ローカルのみです。 読み取ったデータはすべてお使いのマシン上にとどまり、接続した MCP クライアント（ローカルの AI アシスタントなど）にのみ返されます。このサーバーのコードには、外部へのネットワーク接続はありません。src/ のどこにも fetch／http／https クライアントの呼び出しがないことを確認できます。
• お客様自身のデータです。 読み取るのは、ホームフォルダー（~/Library/Group Containers/group.com.apple.stocks/）内にある、ご自身のユーザーアカウントが所有するファイルのみです。他のユーザーのデータ、リモートアカウント、またはそのコンテナ外のものにはアクセスしません。
• テレメトリ、分析、トラッキングはありません。 一切ありません。ツールの結果以外で書き込まれるのは、起動時に stderr へ出力される1行のメッセージ（どのプラットフォームで起動したか）のみです。これは MCP クライアントのローカルログに記録され、外部へ送信されることはありません。
• アクセス権はご自身で管理できます。 最近の macOS バージョンでは、このデータを読み取るアプリ（ターミナルまたは MCP クライアント）に、システム設定でフルディスクアクセスを許可する必要があります。いつでも許可を取り消せば、サーバーはデータを読み取れなくなります。

---

データの取得元

すべてのパスは、ご自身のユーザーコンテナ ~/Library/Group Containers/group.com.apple.stocks/ 内にあります。

データ	ファイル（読み取り専用）
ウォッチリストのシンボル	Library/Documents/PrivateData/com.apple.stocks.private-production-dbstore.json
株価、時価総額	Library/Caches/shared-database（SQLite、quotes テーブル）
ファンダメンタルズ（P/E、EPS、レンジなど）	同じ SQLite キャッシュ（quote_details テーブル）
会社名／取引所	同じ SQLite キャッシュ（stock_metadata テーブル）
日中チャート（OHLCV）	Library/Caches/sparkline-database（SQLite、sparklines テーブル）

これは、apple-notes-mcp など、ほかの macOS MCP サーバーでも採用されている「アプリ独自のローカルストアを読み取る」方法と同じです。お使いの Mac にあるご自身のデータを読み取るもので、自分の情報をエクスポートするのと同様です。DRM を回避したり、アカウントにアクセスしたり、Apple のサービスに接続したりすることはありません。

---

ツール

ツール	機能
list_watchlist	Stocks のウォッチリストにあるすべてのティッカーを（順番どおりに）一覧表示します。
get_quote	ローカルキャッシュから、1つ以上のシンボルの価格と日次変動を取得します。
quote_watchlist	ウォッチリスト内のすべてのシンボルのキャッシュ済み株価を取得します。
stock_details	ファンダメンタルズ：日次および52週レンジ、時価総額、出来高、P/E、EPS、ベータ、配当利回り、次回決算日。
stock_chart	キャッシュ済みの日中 OHLCV チャート（ASCII スパークライン）と、前日終値との比較を取得します。
apple_stock	Apple（AAPL）のファンダメンタルズと、ウォッチリストに含まれているかどうかを取得します。
portfolio_summary	ウォッチリスト全体の分析：上昇／下落銘柄数、上昇率／下落率上位、通貨別・取引所別の内訳。
top_movers	今日のウォッチリストで、上昇率と下落率が最も大きい銘柄を取得します。
search_watchlist	シンボルまたは会社名でウォッチリストを検索します。
stocks_doctor	セットアップを診断します（macOS か、データが存在するか、読み取り可能か、フルディスクアクセスがあるか）。
add_stock	Stocks アプリでシンボルを開き、ワンタップで追加できるようにします（ファイルへの書き込みはありません）。
platform_info	サーバーをこの環境で実行できるかどうかを報告します（常に利用可能。macOS 以外で利用できる唯一のツールです）。

リソース

リソース URI	内容
stocks://watchlist	ウォッチリストのシンボルを1行に1つずつ収録（text/plain）。
stocks://quotes	ウォッチリスト内のすべてのシンボルのキャッシュ済み株価（application/json）。

プロンプト

プロンプト	機能
analyze_portfolio	ウォッチリスト全体を確認し、今日注目すべき点を提示します。
research_stock	1 つの銘柄のファンダメンタルズと日中チャートを取得し、要約します。

add_stock がデータベースに書き込まず、アプリを開く理由

ウォッチリストは、暗号化され、iCloud と同期されるストアに保存されています。手動で編集すると、ウォッチリストが破損して同期に問題が生じるリスクがあります。そのため、add_stock は意図的に何も書き込みません。代わりに stocks:// URL スキームを使って「株価」アプリで銘柄を開き、ワンタップで追加できるようにします。アプリがデータの整合性を保ちます。

---

出力例

以下は、ツールが返す実際のテキスト結果です（表示されている銘柄は一般的な例です）。数値は「株価」アプリのローカルキャッシュから直接取得しています。

apple_stock ／ stock_details AAPL — ファンダメンタルズの概要：

AAPL (Apple Inc.): 299.18 USD  +3.23 (+1.09%) [open]
  Open: 298.44   Day range: 298.07 – 299.75
  52-week range: 196.86 – 317.4
  Market cap: 4.39T   Volume: 11.12M (avg 47.14M)
  P/E: 36.27   EPS: 8.26   Beta: 1.09   Div yield: 0.36%
  Next earnings: 2026-07-30
AAPL is in the watchlist.

stock_chart NVDA — 日中の OHLCV を ASCII スパークラインで表示：

NVDA intraday (7 points)
  ▁▁▂▃▆▇█
  prev close: 204.65   last: 208.69   day range: 207.36 – 208.69
  change vs prev close: +4.04 (+1.97%)

portfolio_summary — ウォッチリスト全体の分析：

Watchlist summary — 98/99 quoted (1 without a cached quote)
  Up: 57   Down: 41   Flat: 0

  Top gainers:
    NVDA: +1.97%
    AMD:  +4.13%
    MSFT: +0.31%
  Top losers:
    INTC: -2.10%
    ...

  By currency:
    USD: 82
    EUR: 16
  By exchange:
    NASDAQ: 38
    NYSE: 35
    XETRA: 9
    ...

get_quote ["AAPL","MSFT","BTC-USD","EGL.LS"] — 米国、暗号資産、欧州のティッカーを含む、銘柄ごとの 1 行表示：

AAPL (Apple Inc.): 299.18 USD  +3.23 (+1.09%) [open]
MSFT (Microsoft Corporation): 378.83 USD  -0.08 (-0.02%) [open]
BTC-USD (Bitcoin USD): 64291.09 USD  -928.50 (-1.42%) [open]
EGL.LS (Mota-Engil, SGPS, S.A.): 4.67 EUR  -0.04 (-0.81%) [open]

各ツールが返す内容

ツール	結果に含まれる主なフィールド
get_quote ／ quote_watchlist	銘柄コード、名称、価格、通貨、日次変動率と変動額、市場の状態
stock_details	上記に加え、始値、日中の値幅、52 週間の値幅、時価総額、出来高と平均出来高、P/E、EPS、ベータ、配当利回り、次回決算日
stock_chart	各ポイントの始値／高値／安値／終値／出来高、前日終値、日中の値幅、前日終値比の変動、ASCII スパークライン
portfolio_summary	引用価格ベースと合計、上昇／下落／横ばいの件数、値上がり上位／値下がり上位、通貨および取引所別の内訳
top_movers	値上がり銘柄と値下がり銘柄の順位（銘柄コード、価格、変動率）

---

要件

• macOS。「株価」アプリを少なくとも 1 回は開いていること（データが存在するようにするため）。
• Node.js ≥ 18。
• システムの sqlite3（/usr/bin/sqlite3）。macOS に付属しています。
• 最近の macOS では、株価コンテナを読み取るために、MCP クライアント（またはターミナル）にフルディスクアクセスが必要な場合があります。ツールが「not found / unreadable」エラーを返す場合は、stocks_doctor ツールを実行し、システム設定 → プライバシーとセキュリティ → フルディスクアクセスでフルディスクアクセスを許可してください。

---

セットアップ

オプション A — npx（インストール不要）

MCP クライアントの設定に以下を追加します（例：Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "apple-stocks": {
      "command": "npx",
      "args": ["-y", "apple-stocks-mcp"]
    }
  }
}

オプション B — ソースから

git clone https://github.com/helderpgoncalves/apple-stocks-mcp.git
cd apple-stocks-mcp
npm install            # also builds via the `prepare` hook

{
  "mcpServers": {
    "apple-stocks": {
      "command": "node",
      "args": ["/absolute/path/to/apple-stocks-mcp/dist/index.js"]
    }
  }
}

Claude Code

MCP サーバーとして追加します。

claude mcp add apple-stocks -- npx -y apple-stocks-mcp

…またはプラグインとしてインストールします（このリポジトリは Claude Code プラグインマーケットプレイスでもあります）。MCP サーバーが自動的に設定されます。

/plugin marketplace add helderpgoncalves/apple-stocks-mcp
/plugin install apple-stocks-mcp@apple-stocks

設定を編集した後、クライアントを再起動してください。

OpenAI Codex

このリポジトリはOpenAI Codex プラグインでもあります。マーケットプレイスを追加してインストールします。

codex plugin marketplace add helderpgoncalves/apple-stocks-mcp
codex plugin install apple-stocks-mcp

または、Codex の設定に通常の MCP サーバーとして追加します（command: npx、args: ["-y", "apple-stocks-mcp"]）。

---

ローカルでのクイックテスト

サーバーは stdio 経由で JSON-RPC を使用します。

printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"apple_stock","arguments":{}}}' \
| npx -y apple-stocks-mcp

出力例：AAPL (Apple Inc.): 299.18 USD +3.23 (+1.09%) [open]

問題がある場合は、組み込みの診断ツールを実行してください。アシスタントに stocks_doctor の実行を依頼するか、次のコマンドを実行します。

printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"stocks_doctor","arguments":{}}}' \
| npx -y apple-stocks-mcp

---

FAQ とトラブルシューティング

ツールのエラーメッセージはわかりやすく、何をすべきかを正確に示してくれるため、 このセクションが必要になることはほとんどありません。迷ったときは、アシスタントに stocks_doctor を実行するよう頼んでください。すべてをチェックし、修正方法を表示します。

初回に許可を求められます。これは正常ですか？

はい。これは、MCP ツールを初めて実行するときに表示される Claude 標準の安全確認プロンプトです。 はい（または、次回から確認を省略するには「はい、今後は確認しない」）を選択してください。エラーではなく、どこにもデータは送信されません。

ツールに「見つからない」または「読み取れない」と表示されます。

メッセージに該当するケースが示されています。原因は次の 2 つです。

1. Stocks アプリを一度も起動していない。 macOS の Stocks アプリを一度開いてデータを作成してから、もう一度試してください。
2. フルディスクアクセス。 最近の macOS では、このサーバーを実行するアプリ（ターミナルまたは MCP クライアント）に フルディスクアクセス を許可する必要があります。
   1. システム設定 → プライバシーとセキュリティ → フルディスクアクセス
   2. ターミナル／MCP クライアントで オン にします（見つからない場合は + で追加します）
   3. そのアプリを完全に終了して再度開いてから、もう一度試してください

stocks_doctor を実行して再確認してください。

初回の呼び出しがタイムアウトする、または「接続に失敗しました」と表示されます。

初回実行時は npx 経由でパッケージをダウンロードするため、少し時間がかかることがあります。もう一度試すか、起動タイムアウトを延長してください。クライアントの起動時に MCP_TIMEOUT=60000（ミリ秒）を指定します。

株価がリアルタイムではないのはなぜですか？

このサーバーは Stocks アプリのローカルキャッシュ、つまりアプリが最後に同期したデータを読み取ります。意図的にネットワーク通信は行いません。データを更新するには、Stocks アプリ（またはそのウィジェット）を開いてください。キャッシュが更新され、次回のツール呼び出しに反映されます。

ウォッチリストの銘柄に「Apple Stocks キャッシュにありません」と表示されます。

問い合わせた時点で、アプリにその銘柄の正確なシンボルの株価がキャッシュされていませんでした（特定の地域の銘柄など、一部のティッカーは常にキャッシュされるとは限りません）。Stocks アプリを開き、その銘柄を一度表示してから、もう一度試してください。ウォッチリストには引き続き表示されます。欠けていたのは株価だけです。

ウォッチリストに株を自動で追加できますか？

add_stock は Stocks アプリで銘柄を開くため、ワンタップで追加できます。アプリの暗号化された iCloud 同期ストアには意図的に書き込みません。書き込みを行うと、ウォッチリストや同期が破損するリスクがあるためです。これは安全性を考慮した判断です。

Linux や Windows でも動作しますか？

いいえ。データは macOS の Stocks アプリのコンテナに保存されているため、このサーバーは macOS 専用です。（解析処理そのものは、合成フィクスチャを使って Linux CI でユニットテストされていますが、実際のデータは macOS にしかありません。）

データがどこかに送信されますか？

いいえ。ソース内でネットワーク通信は一切行われず、ローカルの sqlite3（読み取り専用）と open のみを使用します。読み取った内容は、接続先の MCP クライアントにのみ返されます。プライバシーをご覧ください。

---

開発とテスト

npm run build      # compile to dist/
npm run typecheck  # type-check only
npm test           # build + run the test suite

テストでは test/fixtures/ 内の合成フィクスチャ（生成された dbstore.json と 2 つの小さな SQLite データベース）を使用します。実際の Stocks データに触れることはありません。STOCKS_TEST_MODE=1 を設定すると macOS のチェックが回避されるため、解析／フォーマット処理そのものを任意の OS でテストできます。CI（GitHub Actions、Linux、Node 18/20/22）でもこの方法を使用します。

データパスは環境変数で上書きできます（テストで使用）： STOCKS_DBSTORE_PATH、STOCKS_SHARED_DB_PATH、STOCKS_SPARKLINE_DB_PATH、 STOCKS_SQLITE_BIN

プロジェクト構成

src/
  index.ts           # MCP server: tools, resources, prompts
  appleStocks.ts     # reads your Stocks app data (read-only): watchlist + quotes/details/chart
  bplist-parser.d.ts
test/
  appleStocks.test.ts
  fixtures/          # synthetic data — no personal holdings
docs/
  demo.tape          # VHS script that generates demo.gif
  run-tool.sh        # helper used by the demo
server.json          # MCP Registry metadata
.github/workflows/ci.yml

デモ GIF を再生成するには（VHS が必要です）：

vhs docs/demo.tape   # writes docs/demo.gif

---

法的事項

Apple とは提携していません

これは独立したコミュニティプロジェクトです。Apple Inc. との提携、推奨、後援、支援は一切ありません。「Apple」、「Apple Stocks」、「Stocks」、「macOS」および関連する標章は、Apple Inc. の商標です。これらは、このソフトウェアがどのアプリのローカルデータを読み取るかを事実に即して正確に説明するために記述的な目的に限って使用しています。所有権や推奨を主張または暗示するものではありません。

このプロジェクトには Apple のコード、アセット、商標は含まれておらず、Apple のデータをバンドルまたは再配布することもありません。

データへのアクセス方法

サーバーは、ご自身のユーザーアカウントで、ご自身の Mac にすでに存在するファイルを読み取り専用モードで読み取ります。技術的保護手段や DRM を回避することはなく、オンラインアカウントやサードパーティのデータにアクセスすることも、ご自身のマシンの外部にデータを送信することもありません。キャッシュファイルの形式は macOS のバージョンによって変わることがあります。その場合、ツールは誤動作するのではなく、単に「データなし」を返すことがあります。

投資助言ではありません

すべての数値は Stocks アプリのローカルキャッシュから読み取られるものであり、遅延している場合や不正確な場合があり、現状のまま提供されます。ここに記載されている内容は、投資、金融、法律、税務に関する助言ではありません。ご自身で調査し、取引の判断にこのソフトウェアを頼らないでください。市場データは最終的に、Stocks アプリを通じてサードパーティのプロバイダーから取得され、その利用条件が適用されます。

保証

このソフトウェアは、法律で認められる最大限の範囲で、いかなる種類の保証もなく「現状のまま」提供されます。MIT License をご覧ください。ご自身の責任でご利用ください。

---

ライセンス

MIT © Hélder Gonçalves