apple-stocks-mcp

🍎 apple-stocks-mcp

一款仅适用于 macOS 的 Model Context Protocol（MCP）服务，可让 AI 助手读取 macOS 自带的 Stocks 应用中属于你自己的数据——你的自选股列表，以及该应用已缓存在你的 Mac 上的报价、基本面和日内走势图。

100% 本地运行且只读。它只读取你自己的电脑上、用户主目录下 Stocks 应用容器中已有的文件。它不会发起网络请求、不使用外部 API、不需要 API 密钥，也不会向任何地方发送数据。数据取决于 Stocks 应用上次同步的内容——打开应用即可刷新。

⚠️ **仅适用于 macOS。**数据存储在 macOS Stocks 应用的容器中，因此此服务无法在 Linux 或 Windows 上运行。在非 macOS 主机上，服务仍会启动，但只会提供一个 platform_info 工具，友好地说明其仅适用于 macOS，以及如何移除它——不会出现工具故障或崩溃。

---

快速开始（30 秒）

在 Mac 上，先打开一次 Stocks 应用（以确保数据已存在），然后：

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 的股票表现如何？”*首次使用时，客户端会询问是否允许使用该工具——选择是（或“是，以后不再询问”）即可。就这么简单。如果遇到问题，让它运行 stocks_doctor——它会准确告知你需要修复什么。

---

目录

• 你可以询问什么
• 隐私
• 数据来源
• 工具 · 资源 · 提示词
• 输出示例
• 要求
• 设置
• 常见问题与故障排除
• 开发与测试
• 法律声明

---

你可以询问什么

连接后（参见设置），可以向助手询问以下内容：

• “我的自选股列表里有哪些股票？”
• “今天 Apple 的股票表现如何？”
• “给我看看 NVDA 的基本面。”
• “我持有的股票中，今天涨幅最大的是哪些？”
• “总结一下我的整个自选股列表。”

---

隐私

这是最重要的部分，因此放在最前面。

• 只读。 此服务绝不会修改、删除或写入 Stocks 应用的数据。它使用 sqlite3 的 -readonly 标志打开 SQLite 缓存，并且只解析自选列表文件。唯一看起来会执行写入的操作 add_stock 不会触碰任何文件——它只是让 macOS 在 Stocks 应用中打开某个代码，方便你轻点一下将其添加进去。
• 仅限本地。 读取的每个字节都会留在你的设备上，并且只会返回给你连接的 MCP 客户端（例如你的本地 AI 助手）。此服务的代码没有任何出站网络连接——你可以验证这一点：src/ 中没有任何 fetch/http/https 客户端调用。
• 只读取你自己的数据。 它只读取你用户帐户在个人主文件夹（~/Library/Group Containers/group.com.apple.stocks/）中的文件。它不会访问其他用户的数据、远程帐户或该容器之外的任何内容。
• 没有遥测、没有分析、没有跟踪。 完全没有，永远不会。工具结果之外唯一会写入的内容，是一行发送到 stderr 的启动消息（说明它在哪个平台上启动）——这条消息会进入 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 表）

这与其他 macOS MCP 服务（例如 apple-notes-mcp）采用的“读取应用自己的本地存储”方式相同。它读取的是你自己的 Mac 上的你自己的数据——类似于导出你自己的信息——不会绕过任何 DRM、访问任何帐户，也不会联系任何 Apple 服务。

---

工具

工具	功能
list_watchlist	按顺序列出 Stocks 自选列表中的所有股票代码。
get_quote	从本地缓存获取一个或多个股票代码的价格和当日涨跌。
quote_watchlist	获取自选列表中所有股票代码的缓存报价。
stock_details	基本面数据：当日和 52 周区间、市值、成交量、P/E、EPS、beta、股息收益率、下次财报日期。
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	自选列表中的股票代码，每行一个（text/plain）。
stocks://quotes	自选列表中所有股票代码的缓存报价（application/json）。

提示词

提示词	功能
analyze_portfolio	检查整个自选列表，并指出今天值得关注的内容。
research_stock	获取一个代码对应的基本面数据和日内图表，并进行总结。

为什么 add_stock 会打开应用，而不是写入数据库

自选列表存储在加密且通过 iCloud 同步的存储中。手动编辑可能会损坏自选列表并导致同步失败，因此 add_stock 刻意不会写入任何内容——它使用 stocks:// URL scheme 在 Stocks 应用中打开该代码，你只需轻点一下即可添加，同时应用会保持自身数据一致。

---

示例输出

以下是这些工具实际返回的文本结果（所示代码均为通用示例）。数字直接来自 Stocks 应用的本地缓存。

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 — 以 ASCII 迷你图显示日内 OHLCV 数据：

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"] — 每个代码占一行，涵盖美国、加密货币和欧洲股票代码：

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 周区间、市值、成交量和平均成交量、市盈率、每股收益、贝塔系数、股息率、下一次财报日期
stock_chart	每个数据点的开盘价/最高价/最低价/收盘价/成交量、前收盘价、日内区间、相对前收盘价的涨跌幅、ASCII 迷你图
portfolio_summary	报价总额与总额、上涨/下跌/持平数量、涨幅最大和跌幅最大股票、按货币和交易所分类的明细
top_movers	按涨幅和跌幅排名的股票（代码、价格、涨跌幅）

---

要求

• macOS，且至少打开过一次 Stocks 应用（以确保其数据已生成）。
• Node.js ≥ 18。
• 系统自带的 sqlite3，路径为 /usr/bin/sqlite3（随 macOS 一同提供）。
• 在较新的 macOS 版本中，MCP 客户端（或你的终端）可能需要完全磁盘访问权限才能读取 Stocks 容器。如果工具返回“未找到 / 无法读取”错误，请运行 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

---

常见问题与故障排查

工具的错误消息会清楚地说明问题，并准确告诉你该怎么做， 因此你很少需要查看本节。如有疑问，请让你的助手运行 stocks_doctor——它会检查所有内容并打印修复方法。

第一次使用时会请求权限，这是正常的吗？

是的——这是 Claude 在任何 MCP 工具首次运行时显示的标准安全提示。 选择 是（或选择“是，并且以后不再询问”以跳过后续提示）。这不是 错误，也不会向任何地方发送数据。

工具提示数据“未找到”或“无法读取”。

消息会告诉你具体是哪种情况。原因有两个：

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 和两个小型 SQLite 数据库）运行——绝不会接触你的真实 Stocks 数据。STOCKS_TEST_MODE=1 会绕过 macOS 检查，因此可以在任何操作系统上 测试纯解析 / 格式化逻辑，这也是 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 许可证。使用风险由你自行承担。

---

许可证

MIT © Hélder Gonçalves