🍎 apple-stocks-mcp

A macOS-only Model Context Protocol (MCP) server that lets an AI assistant read your own data from the Stocks app that ships with macOS — your watchlist, and the quotes, fundamentals and intraday charts the app has already cached on your Mac.

100% local and read-only. It reads files that already exist on your own machine, in the Stocks app's container under your home folder. It makes no network requests, uses no external API, needs no API keys, and sends nothing anywhere. The data is whatever the Stocks app last synced — open the app to refresh it.

⚠️ macOS only. The data lives inside the macOS Stocks app's container, so this server does not work on Linux or Windows. On a non-macOS host the server still starts, but exposes a single platform_info tool that politely explains it's macOS-only and how to remove it — no failing tools, no crashes.

Quick start (30 seconds)

On a Mac, open the Stocks app once (so its data exists), then:

Claude Desktop / any MCP client — add this and restart:

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

Claude Code:

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

Then ask: "What's the Apple stock doing today?" The first time, your client asks permission to use the tool — choose Yes (or "Yes, and don't ask again"). That's it. If anything's off, ask it to run stocks_doctor — it tells you exactly what to fix.

Contents

• What you can ask
• Privacy
• Where the data comes from
• Tools · Resources · Prompts
• Example output
• Requirements
• Setup
• FAQ & troubleshooting
• Development & testing
• Legal

What you can ask

Once connected (see Setup), ask your assistant things like:

• "What's in my stock watchlist?"
• "What's the Apple stock doing today?"
• "Show me the fundamentals for NVDA."
• "Which of my stocks are up the most today?"
• "Summarize my whole watchlist."

Privacy

This is the most important section, so it's first.

• Read-only. The server never modifies, deletes, or writes to the Stocks app's data. It opens the SQLite caches with sqlite3's -readonly flag and only parses the watchlist file. The single write-style action, add_stock, does not touch any file — it just asks macOS to open a symbol in the Stocks app so you can add it with a tap.
• Local only. Every byte read stays on your machine and is only returned to the MCP client you connected (e.g. your local AI assistant). There are no outbound network connections in this server's code — you can verify this: there is no fetch/http/https client call anywhere in src/.
• Your own data. It reads only files owned by your user account, in your home folder (~/Library/Group Containers/group.com.apple.stocks/). It does not access other users' data, remote accounts, or anything outside that container.
• No telemetry, no analytics, no tracking. None. Ever. The only thing ever written outside the tool results is a one-line startup message to stderr (which platform it started on) — that goes to your MCP client's local logs and is never sent anywhere.
• You stay in control of access. On recent macOS versions the app reading this data (your terminal or MCP client) must be granted Full Disk Access by you, in System Settings. Revoke it any time and the server can no longer read.

Where the data comes from

All paths are inside your own user container ~/Library/Group Containers/group.com.apple.stocks/:

This is the same "read the app's own local store" approach used by other macOS MCP servers such as apple-notes-mcp. It is reading your data from your Mac — analogous to exporting your own information — and it does not bypass any DRM, access any account, or contact any Apple service.

Tools

Resources

Prompts

Why add_stock opens the app instead of writing the database

The watchlist lives in an encrypted, iCloud-synced store. Editing it by hand risks corrupting your watchlist and breaking sync, so add_stock deliberately does not write anything — it uses the stocks:// URL scheme to open the symbol in the Stocks app, where you add it with one tap and the app keeps its own data consistent.

Example output

These are the actual text results the tools return (symbols shown are generic examples). Numbers come straight from your Stocks app's local cache.

apple_stock / stock_details AAPL — fundamentals at a glance:

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 — intraday OHLCV as an ASCII sparkline:

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 — whole-watchlist analysis:

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"] — one line per symbol, across US / crypto / European tickers:

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]

What each tool returns

Requirements