apple-stocks-mcp

# 🍎 apple-stocks-mcp

[![CI](https://github.com/helderpgoncalves/apple-stocks-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/helderpgoncalves/apple-stocks-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/apple-stocks-mcp?logo=npm)](https://www.npmjs.com/package/apple-stocks-mcp)
[![npm downloads](https://img.shields.io/npm/dm/apple-stocks-mcp?logo=npm&color=cb3837)](https://www.npmjs.com/package/apple-stocks-mcp)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-5965F2)](https://registry.modelcontextprotocol.io/v0/servers?search=apple-stocks-mcp)
[![platform: macOS](https://img.shields.io/badge/platform-macOS-000000?logo=apple)](https://www.apple.com/macos/)
[![Node.js](https://img.shields.io/badge/node-%E2%89%A518-339933?logo=node.js&logoColor=white)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

A **macOS-only** [Model Context Protocol](https://modelcontextprotocol.io) (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.

![apple-stocks-mcp demo](./docs/demo.gif)

> ⚠️ **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:

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

**Claude Code:**

```bash
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](#what-you-can-ask)
- [Privacy](#privacy)
- [Where the data comes from](#where-the-data-comes-from)
- [Tools](#tools) · [Resources](#resources) · [Prompts](#prompts)
- [Example output](#example-output)
- [Requirements](#requirements)
- [Setup](#setup)
- [FAQ & troubleshooting](#faq--troubleshooting)
- [Development & testing](#development--testing)
- [Legal](#legal)

---

## What you can ask

Once connected (see [Setup](#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`](https://github.com/sirmews/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

| 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:

```text
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:

```text
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:

```text
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:

```text
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

| 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 `/us