🍎 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
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/:
| Data | File (read-only) |
|---|
| Watchlist symbols | Library/Documents/PrivateData/com.apple.stocks.private-production-dbstore.json |
| Quotes, market cap | Library/Caches/shared-database (SQLite, quotes table) |
| Fundamentals (P/E, EPS, ranges…) | same SQLite cache (quote_details table) |
| Company names / exchanges | same SQLite cache (stock_metadata table) |
| Intraday chart (OHLCV) | Library/Caches/sparkline-database (SQLite, sparklines table) |
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.
| Tool | What it does |
|---|
list_watchlist | List every ticker in your Stocks watchlist (in order). |
get_quote | Price + daily change for one or more symbols, from the local cache. |
quote_watchlist | Cached quotes for every symbol in the watchlist. |
stock_details | Fundamentals: day & 52-week range, market cap, volume, P/E, EPS, beta, dividend yield, next earnings. |
stock_chart | Cached intraday OHLCV chart (ASCII sparkline) + change vs previous close. |
apple_stock | Apple (AAPL) fundamentals + whether it's in the watchlist. |
portfolio_summary | Whole-watchlist analysis: up/down counts, top gainers/losers, breakdown by currency & exchange. |
top_movers | The biggest gainers and losers in the watchlist today. |
search_watchlist | Search the watchlist by symbol or company name. |
stocks_doctor | Diagnose your setup (macOS? data present? readable? Full Disk Access?). |
add_stock | Opens a symbol in the Stocks app so you can add it with one tap (no file is written). |
platform_info | Report whether the server can run here (always available; the only tool on non-macOS). |
Resources
| Resource URI | Contents |
|---|
stocks://watchlist | The watchlist symbols, one per line (text/plain). |
stocks://quotes | Cached quotes for every watchlist symbol (application/json). |
Prompts
| Prompt | What it does |
|---|
analyze_portfolio | Reviews the whole watchlist and highlights what's notable today. |
research_stock | Pulls fundamentals + intraday chart for one symbol and summarizes it. |
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]
| Tool | Key fields in the result |
|---|
get_quote / quote_watchlist | symbol, name, price, currency, daily change & %, market state |
stock_details | the above plus open, day range, 52-week range, market cap, volume & average volume, P/E, EPS, beta, dividend yield, next earnings date |
stock_chart | per-point open/high/low/close/volume, previous close, day range, change vs previous close, ASCII sparkline |
portfolio_summary | quoted vs total, up/down/flat counts, top gainers/losers, breakdown by currency and exchange |
top_movers | ranked gainers and losers (symbol, price, change %) |
Requirements
- macOS, with the Stocks app opened at least once (so its data exists).
- Node.js ≥ 18.
- The system
sqlite3 at /usr/bin/sqlite3 (ships with macOS).
- On recent macOS versions, the MCP client (or your terminal) may need
Full Disk Access to read the Stocks container. If tools return a
"not found / unreadable" error, run the
stocks_doctor tool, then grant
Full Disk Access in System Settings → Privacy & Security → Full Disk Access.
Setup
Option A — npx (no install)
Add this to your MCP client config (e.g. Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"apple-stocks": {
"command": "npx",
"args": ["-y", "apple-stocks-mcp"]
}
}
}
Option B — from source
git clone https://github.com/helderpgoncalves/apple-stocks-mcp.git
cd apple-stocks-mcp
npm install
{
"mcpServers": {
"apple-stocks": {
"command": "node",
"args": ["/absolute/path/to/apple-stocks-mcp/dist/index.js"]
}
}
}
Claude Code
Add it as an MCP server:
claude mcp add apple-stocks -- npx -y apple-stocks-mcp
…or install it as a plugin (this repo is also a Claude Code plugin
marketplace), which wires up the MCP server for you:
/plugin marketplace add helderpgoncalves/apple-stocks-mcp
/plugin install apple-stocks-mcp@apple-stocks
Restart the client after editing the config.
OpenAI Codex
This repo is also an OpenAI Codex plugin. Add the marketplace and install:
codex plugin marketplace add helderpgoncalves/apple-stocks-mcp
codex plugin install apple-stocks-mcp
Or add it as a plain MCP server in your Codex config (command: npx,
args: ["-y", "apple-stocks-mcp"]).
Quick local test
The server speaks JSON-RPC over stdio:
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
Example output: AAPL (Apple Inc.): 299.18 USD +3.23 (+1.09%) [open]
If anything looks off, run the built-in diagnostics tool — ask your assistant to
run stocks_doctor, or:
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 & troubleshooting
The tools' error messages are self-explanatory and tell you exactly what to do,
so you rarely need this section. When in doubt, ask your assistant to run
stocks_doctor — it checks everything and prints the fix.
It asks for permission the first time. Is that normal?
Yes — that's Claude's standard safety prompt the first time any MCP tool runs.
Choose Yes (or "Yes, and don't ask again" to skip it next time). It's not an
error and nothing is sent anywhere.
A tool says the data is "not found" or "unreadable".
The message tells you which case it is. The two causes:
- The Stocks app has never run. Open the macOS Stocks app once so it creates
its data, then try again.
- Full Disk Access. On recent macOS, the app running this server (your
terminal, or your MCP client) must be granted Full Disk Access:
- System Settings → Privacy & Security → Full Disk Access
- Turn it on for your terminal / MCP client (add it with + if missing)
- Fully quit and reopen that app, then try again
Run stocks_doctor to re-check.
First call times out or shows "failed to connect".
The very first run downloads the package via npx, which can take a moment. Just
try again, or raise the startup timeout: start your client with
MCP_TIMEOUT=60000 (milliseconds).
Why aren't the quotes real-time?
This server reads the Stocks app's local cache — the last data the app
synced. It intentionally makes no network calls. To refresh, open the Stocks app
(or its widget); the cache updates and the next tool call reflects it.
A symbol in my watchlist returns "Not in the Apple Stocks cache".
The app hadn't cached a quote for that exact symbol when you asked (some tickers,
e.g. certain regional listings, aren't always cached). Open the Stocks app and
view the symbol once, then retry. The watchlist still lists it; only its quote
was missing.
Can it add a stock to my watchlist automatically?
add_stock opens the symbol in the Stocks app so you add it with one tap. It
deliberately does not write to the app's encrypted, iCloud-synced store —
that would risk corrupting your watchlist and sync. This is a safety decision.
Does it work on Linux or Windows?
No. The data lives in the macOS Stocks app's container, so the server is
macOS-only. (The pure parsing logic is unit-tested on Linux CI using synthetic
fixtures, but the real data only exists on macOS.)
Is any of my data sent anywhere?
No. There are zero network calls in the source — only local sqlite3
(read-only) and open. Everything read is returned solely to the MCP client you
connected. See Privacy.
Development & testing
npm run build
npm run typecheck
npm test
Tests run against synthetic fixtures in test/fixtures/ (a generated
dbstore.json and two small SQLite databases) — they never touch your real
Stocks data. STOCKS_TEST_MODE=1 bypasses the macOS gate so the pure
parsing/formatting logic can be tested on any OS, which is what CI does
(GitHub Actions, Linux, Node 18/20/22).
Data paths can be overridden via env vars (used by the tests):
STOCKS_DBSTORE_PATH, STOCKS_SHARED_DB_PATH, STOCKS_SPARKLINE_DB_PATH,
STOCKS_SQLITE_BIN.
Project layout
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
To regenerate the demo GIF (requires VHS):
Legal
Not affiliated with Apple
This is an independent, community project. It is not affiliated with,
endorsed by, sponsored by, or supported by Apple Inc. "Apple", "Apple Stocks",
"Stocks", "macOS", and related marks are trademarks of Apple Inc. They are used
here only nominatively — to describe, factually and accurately, which app's
local data this software reads. No claim of ownership or endorsement is made or
implied.
This project ships no Apple code, assets, or trademarks, and does not bundle or
redistribute any Apple data.
How it accesses data
The server reads files that already exist on your own Mac, under your own
user account, in read-only mode. It does not circumvent any technical
protection measure or DRM, does not access any online account or third-party
data, and does not transmit data off your machine. The cache file formats may
change between macOS versions; if that happens, a tool may simply return "no data"
rather than misbehave.
Not financial advice
All figures are read from your Stocks app's local cache, may be delayed or
inaccurate, and are provided as-is. Nothing here is investment, financial,
legal, or tax advice. Do your own research; do not rely on this software for
trading decisions. Market data ultimately originates from third-party providers
via the Stocks app and is subject to their terms.
Warranty
This software is provided "AS IS", without warranty of any kind, to the fullest
extent permitted by law. See the MIT License. Use at your own risk.
License
MIT © Hélder Gonçalves