内容
# google-finance-mcp
谷歌财经的非官方MCP服务器。它允许MCP客户端从您的计算机运行谷歌财经查找工具。
本项目与谷歌无任何关联、也不受谷歌的认可或赞助。它不授予使用谷歌财经数据或任何第三方市场数据的权利。在使用、贡献、打包、发布或部署本项目之前，请查看[法律、用法和贡献政策](LEGAL.md)。
预期用途是本地的、个人的、手动配置的和用户发起的。此包装器作为谷歌财经网页中宣传的端点的执行层，以及在手动交互期间，由可见页面功能提出的、狭隘地记录的运行时请求；它不打算作为托管的API、共享代理、爬虫、定时数据拉取器、数据存储或重新分发服务运行。
## 快速安装适用于Mac用户
如果您只想安装Mac版本并将其连接到MCP客户端，请使用此部分。您不需要为此路径安装Python。
Mac安装程序当前仅为Apple Silicon Macs构建（`arm64`）。如果您使用Intel Mac，请跳转到[从源代码安装Python](#python-install-from-source)。
### 步骤1：在终端中下载并安装
打开**终端**，粘贴这些命令，然后按Enter：
```bash
VERSION=v0.1.2
curl -L -o google-finance-mcp-macos-arm64.pkg \
"https://github.com/woodstock-tokyo/google-finance-mcp/releases/download/${VERSION}/google-finance-mcp-${VERSION}-macos-arm64.pkg"
sudo installer -pkg google-finance-mcp-macos-arm64.pkg -target /
```
您的Mac可能会要求您输入密码，因为安装程序将命令放在：
```text
/usr/local/bin/google-finance-mcp
```
使用终端`curl`下载通常可以避免浏览器添加的`com.apple.quarantine`标记，该标记可能会触发对未签名开源软件包的可怕“Apple无法验证此软件包是否不含恶意软件”警告。
### 步骤2：将它添加到MCP客户端
在MCP客户端配置中，使用此命令路径：
```json
{
"mcpServers": {
"google-finance": {
"command": "/usr/local/bin/google-finance-mcp",
"args": []
}
}
}
```
使用上面的完整路径。桌面应用程序可能不知道`/usr/local/bin`的位置，如果您只写入`google-finance-mcp`。
### 步骤3：使用这些工具启动
连接MCP客户端后，尝试以下工具：
- `google_finance_list_rpcs`：显示当前的谷歌财经首页工具。
- `google_finance_list_quote_rpcs`：显示指定符号和交易所的报价页面工具，例如`NVDA`和`NASDAQ`。
- `google_finance_call_dataset`：按键调用首页数据集。
- `google_finance_call_quote_dataset`：按符号、交易所和数据集键调用报价页面数据集。
如果您使用Safari、Chrome或其他应用程序下载`.pkg`，并且macOS显示恶意软件验证警告，请使用步骤1中的终端命令再次下载。
## 其他简单的发布下载
GitHub发布版包括macOS、Linux和Windows的独立二进制文件。这些工件捆绑了Python和项目依赖项，因此用户无需先安装Python。
### macOS说明
Intel Mac用户应使用Python/`uv`源安装路径。
### Linux
下载Linux `.tar.gz`，解压它，并将二进制文件放在稳定位置，例如 `/usr/local/bin`：
```bash
tar -xzf google-finance-mcp-v0.1.2-linux-x86_64.tar.gz
sudo install -m 755 google-finance-mcp /usr/local/bin/google-finance-mcp
```
然后使用绝对路径配置MCP客户端：
```json
{
"mcpServers": {
"google-finance": {
"command": "/usr/local/bin/google-finance-mcp",
"args": []
}
}
}
```
Linux发布版二进制文件是在Ubuntu 22.04上为`x86_64`构建的。非常旧的Linux发行版可能需要Python源安装路径。
### Windows
下载Windows `.zip`，解压到稳定文件夹，然后将MCP客户端指向`.exe`：
```json
{
"mcpServers": {
"google-finance": {
"command": "C:\\Users\\you\\Apps\\google-finance-mcp\\google-finance-mcp.exe",
"args": []
}
}
}
```
Windows发布构建尚未进行Authenticode签名。Windows SmartScreen可能会在首次运行时显示“Windows保护了您的PC”的警告；选择“更多信息”，然后选择“无论如何都运行”，如果您信任下载的GitHub发布工件。
## 从源代码安装Python
如果您正在开发该项目、使用Intel Mac或无法使用独立发布文件，请使用此路径。
要求：
- Python 3.10或更高版本。上游`mcp`Python SDK不为Python 3.9发布可安装版本，这是许多干净的macOS安装程序通过安装命令行工具后将`/usr/bin/python3`公开为默认值。
- 运行时可以访问`www.google.com`。
- 可以启动stdio服务器的MCP客户端。
如果`python3 --version`报告Python 3.9，则`python3 -m pip install ...`无法安装此软件包，因为其`mcp>=1.0`依赖项需要Python 3.10+。最简单的方法是让`uv`使用托管的解释器，而不是要求用户安装Homebrew Python或Python.org框架构建：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
cd google-finance-mcp
uv tool install --python 3.11 .
```
这将`google-finance-mcp`控制台脚本安装为用户工具。如果macOS没有兼容的解释器，`uv`可能会下载私有Python到其缓存中；它不会替换系统`python3`。
对于从检出进行本地开发，请使用相同的托管Python方法：
```bash
cd google-finance-mcp
uv venv --python 3.11
uv pip install -e ".[dev]"
uv run pytest -q
```
直接运行MCP服务器：
```bash
google-finance-mcp
```
服务器使用MCP stdio传输。它不打印HTTP URL或监听端口；MCP客户端启动命令并通过stdin/stdout进行通信。
## 构建软件包
这是一个纯Python软件包，因此没有本机编译步骤。要构建轮和源代码分发：
```bash
python -m pip install build
python -m build
```
安装构建的轮：
```bash
python -m pip install dist/google_finance_mcp-0.1.0-py3-none-any.whl
```
您也可以在不依赖控制台脚本的情况下运行模块入口点：
```bash
python -m google_finance_mcp
```
要本地构建发布工件：
```bash
bash scripts/build-macos-release.sh
bash scripts/build-linux-release.sh
pwsh scripts/build-windows-release.ps1
```
macOS构建脚本创建一个未签名的`pkgbuild`组件包，并在发布`.pkg`工件之前验证其安装程序`Bom`。这避免了付费的Apple Developer ID依赖，但它不会绕过Gatekeeper对下载安装程序的信任检查。
发布准备从`pyproject.toml`中的版本开始。在发布拉取请求中，更新README下载示例并刷新软件包元数据：
```bash
python scripts/update-readme-release-version.py v<version>
python -m build
```
当发布拉取请求在`master`上生效时，`.github/workflows/prepare-release.yml`验证这些生成的文件已经提交，创建标签`v<version>`，并为该标签发布GitHub发布。工作流程不会将生成的提交推送回`master`，因此它适用于要求更改通过拉取请求进行的分支保护规则。
GitHub发布资产随后由`.github/workflows/release.yml`为该发布标签构建。该准备工作流程在发布后调度资产构建器，构建器将生成的工件上传到该发布，因此直接下载URL如
`https://github.com/woodstock-tokyo/google-finance-mcp/releases/download/v0.1.2/google-finance-mcp-v0.1.2-macos-arm64.pkg`
与`curl`一起工作。
工作流程上传：
- macOS Apple Silicon（`arm64`）`.pkg`、`.tar.gz`和`.sha256`文件。
- Linux `x86_64` `.tar.gz`和`.sha256`文件。
- Windows `x86_64` `.zip`和`.sha256`文件。
## 服务器公开的内容
- `google_finance_list_rpcs`：返回当前的`AF_initDataKeys`和`AF_dataServiceRequests`映射，并附带推断的目的元数据。
- `google_finance_list_known_rpc_purposes`：返回文章的引用RPC ID到目的表。这些ID不被视为稳定。
- `google_finance_refresh_mapping`：强制或重新验证页面映射缓存。
- `google_finance_call_dataset`：按键调用广告首页`ds:*`数据集。
- `google_finance_list_page_rpcs`：返回任何谷歌财经页面路径或URL的当前映射。
- `google_finance_call_page_dataset`：调用任何广告`ds:*`数据集从特定的谷歌财经页面路径或URL。
- `google_finance_list_quote_rpcs`：返回指定股票代码和交易所的报价页面映射。 `/finance/quote/...` 也被接受，目前重定向到 `/finance/beta/quote/...`。
- `google_finance_call_quote_dataset`：为指定股票代码和交易所调用任何广告报价页面`ds:*`数据集。
- `google_finance_get_quote_holdings`：调用报价持有者选项卡的RPC，获取指定股票代码和交易所的原始数据和尽力标签，涵盖政治家持仓、政治家交易、内部交易和分页游标。
- `google_finance_call_rpc`：使用显式请求调用单个RPC ID。显式RPC调用默认为经典`GoogleFinanceUi`端点，也可以选择`endpoint_family: "finhub"`。
- `google_finance_batch_call`：在一次batchexecute POST中调用多个RPC ID。显式批处理调用使用相同的`endpoint_family`选项。
- `google_finance_ds_N_<purpose>`：仅从当前 `/finance/beta` 首页映射生成的动态工具，每个广告beta数据集键一个工具。`ds:N`键是导出的接口标识；当前实时`id`/哈希从`AF_dataServiceRequests`读取，每次映射刷新时。
## MCP客户端配置参考
对于本地可编辑安装，请将MCP客户端指向虚拟环境控制台脚本，以便它始终使用此检出：
```json
{
"mcpServers": {
"google-finance": {
"command": "/absolute/path/to/google-finance-mcp/.venv/bin/google-finance-mcp",
"args": []
}
}
}
```
对于全局安装的轮或软件包，在终端启动的客户端中，使用更短的命令就足够了：
```json
{
"mcpServers": {
"google-finance": {
"command": "google-finance-mcp",
"args": []
}
}
}
```
## 技术细节
服务器获取诸如`https://www.google.com/finance/beta`或`https://www.google.com/finance/beta/quote/NVDA:NASDAQ`等谷歌财经页面，提取`AF_initDataKeys`和`AF_dataServiceRequests`，并使用每个页面的缓存头决定何时刷新内部RPC映射。
### 映射模型
谷歌财经在beta页面上嵌入了如下所示的数据集条目：
```js
var AF_initDataKeys = ["ds:0", "ds:1", "..."];
var AF_dataServiceRequests = {
"ds:1": {id: "vNewwe", request: [null, [null, 1]]}
};
```
此服务器将`ds:N`键视为导出的接口标识。`id`字段是`batchexecute` POST正文中使用的当前实时方法令牌/哈希，它可能会随时间而变化。不要根据硬编码的`id`构建客户端；请通过`ds:N`或生成的`google_finance_ds_N_<purpose>`工具进行调用。
元数据在运行时从实时`AF_dataServiceRequests`条目编译。编译器从实时RPC ID、实时请求形状和`ds:N`页面提示中收集证据，然后在每个元数据对象中记录一个`justification`数组。如果谷歌改变报价页面数据集编号，RPC ID和请求形状证据可以覆盖过时的`ds:N`假设，而无需代码更改。
数据集调用也可以自我修复过时的缓存方法令牌。如果缓存数据集调用返回没有`wrb.fr` batchexecute帧，客户端强制刷新页面HTML，重新解析当前RPC ID和端点，并重试数据集一次。
### 生成的beta工具
这些生成的工具仅适用于谷歌财经beta首页（`/finance/beta`）。含义已针对2026-06-23的实时beta页面进行了验证。下面示例中的`id`值可能会发生变化；服务器会从`AF_dataServiceRequests`刷新它们。
| 数据集 | 示例实时ID | 生成的工具 | 含义 | 默认请求 |
| --- | --- | --- | --- | --- |
| `ds:0` | `hgueg` | `google_finance_ds_0_market_overview_quotes` | 市场概览报价 | `[1]` |
| `ds:1` | `vNewwe` | `google_finance_ds_1_equity_sectors` | 股票板块 | `[null,[null,1]]` |
| `ds:2` | `HGhSgc` | `google_finance_ds_2_earnings_calendar` | 盈利日历 | `[1,0,2]` |
| `ds:3` | `HGhSgc` | `google_finance_ds_3_earnings_calendar_secondary` | 盈利日历（次要）目前为空 | `[3,1]` |
| `ds:4` | `hgueg` | `google_finance_ds_4_market_overview_charts` | 市场概览图表，附带SVG火花线 | `[0]` |
| `ds:5` | `HacE5d` | `google_finance_ds_5_market_summary_news_clusters` | 市场总结新闻集群 | `["market_summary",1]` |
| `ds:6` | `MlXU3e` | `google_finance_ds_6_top_finance_articles` | 财经要闻 | `[8]` |
| `ds:7` | `kA4MVd` | `google_finance_ds_7_market_news` | 市场新闻 | `[2,20]` |
| `ds:8` | `YtbmEe` | `google_finance_ds_8_market_movers` | 市场动向 | `[[2,3,1],4,0]` |
| `ds:9` | `RiQiSd` | `google_finance_ds_9_empty_initialization_endpoint` | 空初始化端点 | `[null,null,25]` |
| `ds:10` | `X12h2b` | `google_finance_ds_10_empty_initialization_endpoint` | 空初始化端点 | `[]` |
文章的ID，如`xh8wxf`、`HqGpWd`和`YtbmEe`，仅作为参考示例。调用使用每个`ds:N`条目当前关联的实时ID。
### 报价页面数据集发现
经典报价网址如 `/finance/quote/GOOGL:NASDAQ` 被服务器接受，目前会重定向到 `/finance/beta/quote/GOOGL:NASDAQ`。重定向的报价页面会公布 `ds:0` 到 `ds:20`。这些不是生成的 `google_finance_ds_N_<purpose>` 工具；请使用 `google_finance_call_quote_dataset` 或 `google_finance_call_page_dataset` 调用它们。
这些含义是根据2026-06-23的实时报价页面和响应有效载荷发现的，使用`NVDA:NASDAQ`。
| 数据集 | 示例实时ID | 含义 | 默认请求形状 | 备注 |
| --- | --- | --- | --- | --- |
| `ds:0` | `hgueg` | 市场概览报价 | `[1]` | 符号无关的市场报价组。 |
| `ds:1` | `vNewwe` | 股票板块 | `[null,[null,1]]` | 板块绩效列表。 |
| `ds:2` | `gCvqoe` | 报价摘要 | `[[tuple],1]` | 所请求证券的主要报价载荷。 |
| `ds:3` | `JL8oKc` | 公司简介 | `[[tuple]]` | 长期公司/证券简介和描述字段。 |
| `ds:4` | `SICF5d` | 相关证券 | `[tuple,4]` | 比较的同行/相关报价卡。 |
| `ds:5` | `YTM9q` | 分析师评级和目标价 | `[tuple]` | 分析师共识、目标价范围和最近的分析师行动。 |
| `ds:6` | `Kcy68c` | 盈利历史和预测 | `[[tuple],1]` | 带有实际和估计收入/每股收益字段的季度行。 |
| `ds:7` | `XxQsbd` | 盈利历史和预测替代 | `[[tuple],1]` | 替代季度行，带有实际和估计收入/每股收益字段。 |
| `ds:8` | `ADgT7b` | 证券概览卡 | `[[tuple],1,1,1]` | 价格、市值、行业、徽标和摘要报价字段。 |
| `ds:9` | `c2u4wc` | 分时图表点 | `[[tuple],1]` | 每分钟价格点。 |
| `ds:10` | `c2u4wc` | 分时OHLCV图表 | `[[tuple],1,null,null,null,null,null,1]` | 分时蜡烛行，带有开盘、收盘、高、最低、时间戳和交易量。 |
| `ds:11` | `c2u4wc` | 一个月图表点 | `[[tuple],3]` | 每日价格点。 |
| `ds:12` | `c2u4wc` | 一个月OHLCV图表 | `[[tuple],3,null,null,null,null,null,1]` | 每日蜡烛行，带有开盘、收盘、高、最低、时间戳和交易量。 |
| `ds:13` | `gXxkFd` | 关键统计数据/比率 | `[["SYMBOL","EXCHANGE"]]` | 紧凑的数值比率向量。响应包括`labeled_data`，带有尽力标签和保留的原始索引。 |
| `ds:14` | `gCvqoe` | 报价摘要替代 | `[[tuple]]` | 报价载荷，没有尾随模式标志。 |
| `ds:15` | `dlNq8b` | 证券概览卡替代 | `[[tuple],1,1,1]` | 替代价格、市值、行业、徽标和摘要报价字段。 |
| `ds:16` | `Pr8h2e` | 财务/预测 | `[[tuple],null,1]` | 财务报表和预测数组。 |
| `ds:17` | `kA4MVd` | 市场新闻源 | `[2,12,[tuple]]` | 通用市场或相关新闻列表。 |
| `ds:18` | `kA4MVd` | 证券新闻源 | `[5,12,[tuple]]` | 公司/证券特定文章列表。 |
| `ds:19` | `RiQiSd` | 空初始化端点 | `[null,null,25]` | 初始化请求，返回空数据数组。 |
| `ds:20` | `X12h2b` | 空初始化端点 | `[]` | 初始化请求，返回空数据数组。 |
### 报价持有者选项卡RPC
报价页面的持有者选项卡在`AF_dataServiceRequests`的`ds:*`映射中不可见。它由2026-07-02的实时页面网络流量中观察到的渲染时间FinHub RPC加载。
| RPC ID | 工具 | 默认请求形状 | 备注 |
| --- | --- | --- | --- |
| `K5Y6Xb` | `google_finance_get_quote_holdings` | `[[null,["SYMBOL","EXCHANGE"]]]` | 返回政治家持仓、政治家交易、内部交易和分页游标。 |
由于此方法令牌不作为页面数据集公布，因此像`ds:N`调用一样对待它。该工具保留原始的batchexecute有效载荷，并添加`labeled_data`，包含从渲染的持有者选项卡和观察到的响应行推断的结构标签。内部交易行包括`insider_name`、`position`、`transaction_type`、`transaction_date`、`shares`、`amount`、`currency`和`sec_form4_url`等字段。
### 端点处理
经典显式RPC调用使用：
```text
https://www.google.com/finance/_/GoogleFinanceUi/data/batchexecute
```
当前beta页面宣传了FinHubUi端点，数据集调用使用与页面映射关联的端点：
```text
https://www.google.com/finance/beta/_/FinHubUi/data/batchexecute
```
生成的`google_finance_ds_N_<purpose>`工具专门用于beta首页。其他页面，包括报价页面或经典的`/finance/...`路径，可以使用`google_finance_list_page_rpcs`或`google_finance_list_quote_rpcs`进行检查，并使用`google_finance_call_page_dataset`、`google_finance_call_quote_dataset`、`google_finance_call_rpc`或`google_finance_batch_call`进行调用。
请求体是URL编码的`f.req`值，包含批处理RPC调用。响应是谷歌的batchexecute帧；服务器剥离反JSON前缀，解码`wrb.fr`帧，并返回结构化JSON。
通用`google_finance_call_rpc`和`google_finance_batch_call`接受显式`source_path`和`endpoint_family: "classic" | "finhub"`。数据集调用使用获取的页面路径和默认端点，因此首页和报价页面都可以定义`ds:0`、`ds:1`等，而无需共享含义。
## 烟雾测试
快速的本地导入和实时映射检查：
```bash
python - <<'PY'
import anyio
from google_finance_mcp.client import GoogleFinanceClient
async def main():
client = GoogleFinanceClient()
mapping = await client.get_mapping(force_refresh=True)
print(mapping.source_path)
print(sorted(mapping.requests))
anyio.run(main)
PY
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器