benethos-yahoo-finance-mcp

非官方 Yahoo Finance MCP 服务

一个 MCP 服务，可向 MCP 客户端（例如 Claude Desktop）提供 Yahoo Finance 数据。它通过 stdio（默认方式，适用于本地客户端）或 HTTP 传输（适用于独立部署或容器化托管）运行。市场数据通过 yfinance 库获取，该库使用 Yahoo 的非官方接口。

免责声明

• 本项目与 Yahoo 无关，也未获其认可或赞助。“Yahoo”和“Yahoo Finance”是其各自所有者的商标。
• 本项目通过 yfinance 使用 Yahoo Finance 的非官方接口。这些接口随时可能变更或失效，Yahoo 也可能限制请求频率或屏蔽请求。使用前请查阅 Yahoo 的服务条款。
• 数据可能存在延迟、不完整或不准确的情况。**此处内容均不构成财务建议。**请勿将其作为交易或投资决策的依据。
• 本项目按“原样”提供，不附带任何保证。仅供个人和教育用途。使用风险由您自行承担。请参阅 LICENSE。
• 用于商业用途时，请查阅 Yahoo 的服务条款，并考虑改用获得适当许可的市场数据提供商，而非使用非官方接口。

目录

• 用途
  • 提示词示例
• 工具
• 股票代码解析
• 兼容的客户端
• 要求
• 安装
  • 快速开始：Claude Desktop 扩展
  • 使用 uv 配置 Claude Desktop（手动配置）
  • 其他安装方式
• 作为独立服务运行
  • Docker
  • Docker Compose
  • 手动安装（uv 或 venv）
• 缓存
  • 何时启用
• 开发
• 商标

用途

该服务可让 Claude Desktop 等 MCP 客户端基于 Yahoo Finance 的实时数据回答市场相关问题：股票价格及其走势、公司的营收、分析师的预期、持股人、ETF 的持仓，以及某个行业或市场的表现。你用日常语言提问，客户端选择工具，答案则基于 Yahoo 返回的数据，而非模型的记忆。

典型用途：

• 在聊天中快速查询。 查看报价、52 周区间、下一次财报日期或股息历史，无需打开浏览器。
• 研究一家公司的情况。 在一次对话中查看公司简介、财务报表、预期、评级变动、持股人和内部人士交易，并由模型总结。
• 进行比较。 并排比较多个股票代码，查看某个行业或产业中的头部公司，或查看 ETF 的持仓及权重。
• 基于原始数据进行计算。 获取 6 个月的每日收盘价序列，用于计算 RSI、MACD 或回撤，再由模型根据该序列得出结果。
• 运行共享服务。 通过 HTTP 在 Docker 中运行，供团队的 Web 前端或 n8n 等自动化工具使用，并可选择在 Yahoo 前添加结果缓存。

所有操作均为只读。该服务不会下单、不持有投资组合，也不会登录任何账户。数据来自非官方端点，可能存在延迟，不能作为交易决策的依据；请参阅上文的免责声明。

示例提示词

连接服务后，用自然语言向客户端提问，它会选择相应的工具。请将方括号中的占位符替换为具体值。

价格与报价

• “[Ticker] 当前价格是多少？与其 52 周高点相差多少？”
• “[Ticker] 的交易价格高于还是低于其 50 日和 200 日移动平均线？”
• “获取 [Ticker] 过去 6 个月的每日收盘价，并计算 RSI 和 MACD。”
• “[Ticker] 过去 12 个月的最大回撤是多少？”
• “比较 [Ticker A] 和 [Ticker B] 过去 3 个月的表现，看看哪只股票更抗跌。”
• “获取 [Ticker A]、[Ticker B] 和 [Ticker C] 的当前报价，并用表格进行比较。”

公司与估值

• “告诉我 [Ticker] 的市盈率、贝塔系数、市值和股息率。”
• “[Company name] 实际上是做什么的？属于哪个板块和行业？”
• “展示 [Ticker] 最近三年的年度利润表，以及营收的发展情况。”
• “[Ticker] 的股数在过去几年里有何变化？这意味着回购还是稀释？”

分析师与新闻

• “[Ticker] 的分析师共识是什么？平均目标价与当前价格相差多少？”
• “[Ticker] 最近几周有评级上调或下调吗？”
• “[Ticker] 的未来营收和每股收益（EPS）预估是多少？近期有何调整？”
• “总结 [Ticker] 的近期新闻。”

财报与日历

• “[Ticker] 下一次何时发布财报？预计每股收益（EPS）是多少？”
• “[Ticker] 最近几个季度的业绩与预估相比如何？”
• “[Ticker] 下一次财报发布日期和除息日是什么时候？”

股息

• “展示 [Ticker] 过去十年的股息和当前股息率。”
• “[Ticker] 过去 20 年里下调过股息吗？拆分过股票吗？”

所有权与内部人士

• “[Ticker] 最大的机构持有人有哪些？”
• “[Ticker] 有多少股份由内部人士持有，有多少由机构持有？”
• “最近 [Ticker] 有值得关注的内部人士买入或卖出吗？”

基金与 ETF

• “ETF [Ticker] 的主要持仓和板块权重是什么？”
• “[ETF Ticker] 的资产类别构成如何？由哪家基金公司管理？”

文件

• “展示 [US Ticker] 最新的 SEC 文件并附上链接。”

期权

• “[US Ticker] 有哪些可选的期权到期日？”
• “展示 [US Ticker] 在 [Date] 到期的看涨期权和看跌期权。”

板块与市场

• “科技板块中规模最大的公司和行业有哪些？”
• “展示半导体行业表现最佳的公司。”
• “美国市场现在开盘了吗？下一次开盘是什么时候？”
• “欧洲和亚洲的主要指数收盘表现如何？”

筛选

• “找出股息率高于 4 % 且市盈率低于 15 的美国股票。”
• “哪些公司连续至少 25 年提高股息？”
• “列出德国上市的规模最大的科技股，要求市盈率为正且低于 20。”

查找代码

• “[Company name] 在 [Exchange] 上对应的 Yahoo 股票代码是什么？”
• “将 ISIN [ISIN] 解析为 Yahoo 股票代码。”

每日简报

• “针对 [Ticker A]、[Ticker B] 和 [Ticker C]：获取报价、过去 6 个月的历史数据、公司信息和分析师建议，然后分别简要介绍一下。”

**服务本身不会进行任何计算。**它会转发 Yahoo 返回的数据，其中已经包含移动平均线、市盈率、贝塔系数和股息率等衍生数据。对于 Yahoo 未提供的数据——RSI、MACD、回撤、情绪、总回报——模型会根据原始数据序列进行计算。

工具

每个工具都只读取数据，并通过 MCP 注解 readOnlyHint 和 openWorldHint 向客户端说明这一点。遵循这些注解的客户端可以在不每次征求确认的情况下运行工具。每个工具还有一个简短标题，例如“股票筛选器”，客户端可以用它代替工具名称显示。

工具	描述
search	按名称、股票代码或 ISIN 查找金融工具，并返回 Yahoo 符号。
get_quote	获取某个符号的当前价格和关键盘中数据。
get_quotes	一次获取多个符号的简明实时报价（列出未找到的符号）。
get_history	获取历史 OHLCV 数据（按周期／间隔或指定日期范围）。
get_company_info	获取公司简介和关键统计数据（行业、市值、市盈率等）。
get_financials	获取损益表、资产负债表或现金流量表（年度／季度／ttm）。
get_dividends	获取股息和股票拆分历史。
get_news	获取近期新闻标题（标题、摘要、发布方、URL），最多返回 Yahoo 提供的 10 条；如果该符号自身没有新闻，则从 Yahoo 搜索结果中获取。
get_recommendations	获取分析师评级趋势和目标价。
get_options	获取期权到期日，以及指定日期的看涨／看跌期权链（以平值为中心）。
get_earnings	获取即将公布和历史财报数据（EPS 预估／实际值、意外幅度）。
get_estimates	获取分析师前瞻预估（盈利、营收、EPS 趋势／修订、增长）。
get_upgrades_downgrades	获取近期分析师评级变动（上调／下调）。
get_holders	获取所有权构成（内部人士／机构持股比例、主要机构和共同基金持有人）。
get_insider_activity	获取内部人士交易、6 个月买入／卖出摘要和当前名册。
get_sec_filings	获取近期 SEC 文件（类型、日期、标题、EDGAR／附件链接）。
get_calendar	获取即将公布的财报日期和股息／除息日期，以及预估范围。
get_shares	获取流通股历史（日期 → 股数）；默认覆盖最近 18 个月，除非指定开始日期。
get_fund_data	获取基金／ETF 简介：概览、资产类别和行业权重、主要持仓。
get_sector	按键浏览市场行业：概览、主要公司／ETF／基金、细分行业。
get_industry	按键浏览细分行业：概览、上级行业、主要／表现最佳／增长最快的公司。
get_market	获取某个市场（US、EUROPE、ASIA 等）的交易状态和主要指数摘要。
screen	按条件筛选股票（股息率、市盈率、市值、地区、行业等），并按排名列出及显示匹配总数。

大多数 get_* 工具都接受 Yahoo Finance 符号——股票代码（AAPL、 SAP.DE）或纯 ISIN。使用 search 将公司名称转换为符号。以下四个 工具例外：get_sector 和 get_industry 接受行业或细分行业 键（例如 technology、semiconductors），get_market 接受市场 键（例如 US），而 screen 接受 筛选条件，例如 {"field": "dividend_yield", "op": "gt", "value": 3}，并自行查找符号。

📊 行业与细分行业键 — 点击展开（11 个行业、145 个细分行业，由程序生成）

basic-materials（14 个） agricultural-inputs、aluminum、building-materials、chemicals、coking-coal、copper、gold、lumber-wood-production、other-industrial-metals-mining、other-precious-metals-mining、paper-paper-products、silver、specialty-chemicals、steel

communication-services（7 个） advertising-agencies、broadcasting、electronic-gaming-multimedia、entertainment、internet-content-information、publishing、telecom-services

consumer-cyclical（23 个） apparel-manufacturing、apparel-retail、auto-manufacturers、auto-parts、auto-truck-dealerships、department-stores、footwear-accessories、furnishings-fixtures-appliances、gambling、home-improvement-retail、internet-retail、leisure、lodging、luxury-goods、packaging-containers、personal-services、recreational-vehicles、residential-construction、resorts-casinos、restaurants、specialty-retail、textile-manufacturing、travel-services

**`consumer-defensive`**（12） `beverages—brewers`、`beverages—non-alcoholic`、`beverages—wineries-distilleries`、`confectioners`、`discount-stores`、`education-training-services`、`farm-products`、`food-distribution`、`grocery-stores`、`household-personal-products`、`packaged-foods`、`tobacco`

energy（8） oil-gas-drilling、oil-gas-e&p、oil-gas-equipment-services、oil-gas-integrated、oil-gas-midstream、oil-gas-refining-marketing、thermal-coal、uranium

financial-services（15） asset-management、banks—diversified、banks—regional、capital-markets、credit-services、financial-conglomerates、financial-data-stock-exchanges、insurance-brokers、insurance—diversified、insurance—life、insurance—property-casualty、insurance—reinsurance、insurance—specialty、mortgage-finance、shell-companies

healthcare（11） biotechnology、diagnostics-research、drug-manufacturers—general、drug-manufacturers—specialty-generic、health-information-services、healthcare-plans、medical-care-facilities、medical-devices、medical-distribution、medical-instruments-supplies、pharmaceutical-retailers

industrials（25） aerospace-defense、airlines、airports-air-services、building-products-equipment、business-equipment-supplies、conglomerates、consulting-services、electrical-equipment-parts、engineering-construction、farm-heavy-construction-machinery、industrial-distribution、infrastructure-operations、integrated-freight-logistics、marine-shipping、metal-fabrication、pollution-treatment-controls、railroads、rental-leasing-services、security-protection-services、specialty-business-services、specialty-industrial-machinery、staffing-employment-services、tools-accessories、trucking、waste-management

real-estate（12） real-estate-services、real-estate—development、real-estate—diversified、reit—diversified、reit—healthcare-facilities、reit—hotel-motel、reit—industrial、reit—mortgage、reit—office、reit—residential、reit—retail、reit—specialty

technology（12） communication-equipment、computer-hardware、consumer-electronics、electronic-components、electronics-computer-distribution、information-technology-services、scientific-technical-instruments、semiconductor-equipment-materials、semiconductors、software—application、software—infrastructure、solar

utilities（6） utilities—diversified、utilities—independent-power-producers、utilities—regulated-electric、utilities—regulated-gas、utilities—regulated-water、utilities—renewable

符号解析

所有 get_* 工具都需要 Yahoo Finance 符号。股票代码（AAPL、 SAP.DE）和纯 ISIN（US0378331005）均可使用。ISIN 由 yfinance 自行解析：任何符合 ISIN 格式的内容，都会在创建 ticker 对象时通过 Yahoo 搜索进行查询；此后，找到的 ticker 会代替它使用。 服务会原样传递符号，仅进行去除首尾空白和转为大写的处理，并回显收到的内容。符号最多 32 个字符，且格式与 Yahoo 使用的格式一致，仅包含字母、数字和 . - ^ = &，例如 ^GSPC、EURUSD=X 或 BRK-B。其他任何内容，以及 Yahoo 无法解析的 ISIN 格式字符串，都会返回未知符号。

要将公司名称转换为符号，请先调用 search——同一个 Yahoo 搜索端点可处理自由文本、股票代码和 ISIN。无论如何，股票代码都比 ISIN 更合适，因为这样返回的 symbol 在各工具间会保持一致。

有两点需要注意。ISIN 可以使用，这是对非官方端点行为的观察， 并非保证：早期版本中无法使用，之后也可能再次失效。 此外，德国 WKN 无法通过任何途径解析，无论是这些工具还是 search 都不行——Yahoo 不提供 WKN 查询，因此请改用股票代码、ISIN 或公司名称。

兼容的客户端

MCP 是一种开放协议，因此此服务不绑定于某个应用。每个 MCP 客户端都可以使用它。区别仅在于客户端使用哪种传输方式，这决定了如何启动服务。

本地通过 stdio 通信。 客户端将服务作为子进程启动，并通过 stdin 和 stdout 与其通信。这是默认传输方式，无需网络。Claude Desktop、Claude Code、Cursor、VS Code（Copilot Agent 模式）、Zed、Windsurf、JetBrains AI 助手、Cline、Roo Code、Continue 和 Goose 都支持这种方式。Claude Desktop 也支持将服务作为扩展使用，只需打开一个文件，详见快速入门。不同客户端的配置文件各不相同，但命令始终是使用 uv 的 Claude Desktop下所示的命令：

{ "command": "uvx", "args": ["benethos-yahoo-finance-mcp"] }

通过网络使用 streamable-HTTP。 服务只需运行一次，客户端即可连接到 http://<host>:8000/mcp；如果在生产 compose 文件的 Caddy 配置下使用 bearer token，则可连接到 https://<domain>/mcp。使用 --transport streamable-http 启动，或使用默认提供此传输方式的 Docker 镜像。基于浏览器的前端和多用户前端需要这种方式——Open WebUI 原生支持通过 streamable-HTTP 使用 MCP，不支持其他传输方式，因为共享的 Web 前端无法为每个用户各自运行一个 stdio 进程。LibreChat 和 Windsurf 除了支持 stdio，也支持这种方式。

通过网络使用 SSE。 这是一种较旧的 HTTP 传输方式，部分客户端仍要求使用。使用 --transport sse 启动，并将客户端指向 http://<host>:8000/sse。n8n 中的 MCP Client Tool 节点通过这种方式连接。

默认情况下，两种 HTTP 传输方式都是开放的，并由 Host 允许列表和可选的 bearer token 进行保护。公开其中任意一种之前，请先阅读作为独立服务运行下的说明。

没有列出你的客户端？ 客户端支持情况变化很快。请确认你的客户端支持哪种传输方式，然后使用上面对应的命令——传输方式很稳定，但客户端名称列表未必如此。

要求

• uv（推荐）——通过一个工具管理 Python、虚拟环境和依赖项。
• 或者，不使用 uv：Python 3.11+，以及 pip / venv。
• 只有选择从源代码安装时才需要 git。

安装

快速入门：Claude Desktop 扩展

这是 Claude Desktop 最简单的使用方式。无需事先安装任何内容，不需要 uv、Python 或配置文件：Claude Desktop 会提供扩展所需的内容。

1. 下载 benethos-yahoo-finance-mcp.mcpb，即最新版本的扩展。每个版本也会在发布页面中提供对应版本的扩展。
2. 打开文件：双击文件，或将其拖到 Claude Desktop → Settings → Extensions。Claude Desktop 会显示可用工具并询问是否安装。
3. 在新聊天中询问需要市场数据的问题。首次启动时会安装依赖项，需要几秒钟；之后启动会很快。

如果服务也列在 claude_desktop_config.json 中，请删除该条目，否则每个工具都会显示两次。此扩展仅适用于 Claude Desktop。其他客户端请使用下面的命令。

使用 uv 在 Claude Desktop 中手动配置

无需克隆、无需手动创建虚拟环境，也无需使用 git。uvx 会按需从 PyPI 获取并运行此软件包（发布名称为 benethos-yahoo-finance-mcp）。

1. 安装 uv（如果尚未安装）—— uv 安装页面 涵盖了所有平台。它会提供 uvx，这里仅需安装这一项。

2. 将服务添加到 claude_desktop_config.json（Claude Desktop → 设置 → 开发者 → 编辑配置）：

   {
     "mcpServers": {
       "benethos-yahoo-finance-mcp": {
         "command": "uvx",
         "args": ["benethos-yahoo-finance-mcp"]
       }
     }
   }
   

   如需保持稳定，可固定版本为 benethos-yahoo-finance-mcp==0.8.8。要启用可选的结果缓存，请添加 env 块，例如 "env": { "YF_MCP_CACHE": "1" }（参见缓存）。

3. 重启 Claude Desktop（从系统托盘退出，而不只是关闭窗口）。 随后工具便会显示在客户端中。

要从源代码安装吗？ 你可以使用 uvx --from "git+https://github.com/benethos-hub/yahoo-finance-mcp.git" benethos-yahoo-finance-mcp 运行尚未发布的 main 分支。 此方式要求客户端启动的进程能够在 PATH 中找到 git——有些图形界面客户端不会传递完整的 PATH，因此建议使用上面的 PyPI 安装方式。

客户端使用的 PATH 中必须包含 uvx。安装 uv 后，请彻底重启应用——或者将 uvx 的绝对路径用作 command。首次启动时会下载软件包及其依赖项，因此需要稍等片刻。后续启动将使用缓存。

其他安装方式

从 MCP Registry 安装。 从 0.8.2 起的每个版本都已列入官方 MCP Registry，名称为 io.github.benethos-hub/benethos-yahoo-finance-mcp，其中包含 PyPI 软件包和 容器镜像；从 0.8.4 起也包含 Claude Desktop 安装包 （条目）。 从注册表安装的客户端会使用 uvx 启动服务，或者使用 docker run -i --rm 和 --transport stdio 启动，无需设置。从 0.8.3 起，容器条目也会以只读模式运行，不启用任何功能，也不进行 HTTP 健康检查，与 Docker 中经过加固的 docker run 示例一致。VS Code 扩展视图中的 MCP 列表（@mcp）是 GitHub 自行挑选的；列入注册表并不意味着服务也会出现在该列表中。

通过 pip 从 PyPI 安装（无需 uv，也无需克隆）。将已发布的软件包安装到虚拟环境中，并以模块形式运行。平台间唯一的区别是 venv 解释器路径：Windows 使用 .venv\Scripts\python.exe，Linux/macOS 使用 .venv/bin/python。

# Windows (PowerShell)
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install benethos-yahoo-finance-mcp

# Linux / macOS (bash)
python3 -m venv .venv
.venv/bin/python -m pip install benethos-yahoo-finance-mcp

让 Claude Desktop 指向 venv 解释器的绝对路径并运行该模块（无需使用生成的控制台脚本）：

{
  "mcpServers": {
    "benethos-yahoo-finance-mcp": {
      "command": "/abs/path/to/.venv/bin/python",
      "args": ["-m", "benethos_yahoo_finance_mcp"]
    }
  }
}

（在 Windows 上，将 C:\\abs\\path\\to\\.venv\\Scripts\\python.exe 用作 command。）

使用 uv 从源代码安装（用于开发或本地修改）：

git clone https://github.com/benethos-hub/yahoo-finance-mcp.git
cd yahoo-finance-mcp
uv sync --extra dev          # creates .venv + installs deps from uv.lock
uv run benethos-yahoo-finance-mcp     # run over stdio

让 Claude Desktop 指向检出目录：

{
  "mcpServers": {
    "benethos-yahoo-finance-mcp": {
      "command": "uv",
      "args": ["run", "--project", "/abs/path/to/yahoo-finance-mcp", "benethos-yahoo-finance-mcp"]
    }
  }
}

使用 venv 和 pip 从源代码安装（无需 uv）。平台间唯一的区别是 venv 解释器路径：Windows 使用 .venv\Scripts\python.exe，Linux/macOS 使用 .venv/bin/python。

# Windows (PowerShell)
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .

# Linux / macOS (bash)
python3 -m venv .venv
.venv/bin/python -m pip install -e .

Claude Desktop 配置使用 venv 解释器的绝对路径：

{
  "mcpServers": {
    "benethos-yahoo-finance-mcp": {
      "command": "/abs/path/to/.venv/bin/python",
      "args": ["-m", "benethos_yahoo_finance_mcp"]
    }
  }
}

（在 Windows 上，将 C:\\abs\\path\\to\\.venv\\Scripts\\python.exe 用作 command。）

作为独立服务运行

如需在 Claude Desktop 之外使用——作为可通过网络访问的 HTTP 服务——请运行 HTTP 传输模式（streamable-http 或 sse）。使用 Docker 是最简单的方式。

每个选项都同时提供 CLI 标志和环境变量（便于在容器中使用），但下面注明的一个例外情况除外。优先级为CLI > 环境变量 > 默认值（--help 会列出各标志）：

标志	环境变量	默认值	描述
--version	—	—	打印版本并退出。与服务在 MCP 握手中报告的值相同。
--transport	YF_MCP_TRANSPORT	stdio	stdio、streamable-http 或 sse。
--host	YF_MCP_HOST	127.0.0.1	HTTP 传输的绑定主机（远程访问时使用 0.0.0.0）。
--port	YF_MCP_PORT	8000	HTTP 传输的端口（1 到 65535）。
--path	YF_MCP_PATH	/mcp（sse 时为 /sse）	HTTP 传输的 URL 路径。
(none)	YF_MCP_BEARER_TOKEN	未设置	要求每个 HTTP 请求都携带此 bearer token。仅支持通过环境变量设置，刻意不提供命令行参数：参数会显示在进程列表中。
--allowed-hosts	YF_MCP_ALLOWED_HOSTS	见下文，或根据 origins 推导	以逗号分隔的 Host 标头允许列表，用于 DNS 重绑定防护。
--allowed-origins	YF_MCP_ALLOWED_ORIGINS	根据 hosts 推导	以逗号分隔的 Origin 标头允许列表。
--log-level	YF_MCP_LOG_LEVEL	INFO	DEBUG/INFO/WARNING/ERROR/CRITICAL。
--cache / --no-cache	YF_MCP_CACHE	关闭	启用/禁用持久化结果缓存。
--cache-dir	YF_MCP_CACHE_DIR	OS 缓存目录	缓存文件所在目录。
--cache-max-entries <N>	YF_MCP_CACHE_MAX_ENTRIES	10000	缓存保留的最大条目数；超出时最早的条目会先被移除。
--cache-ttl <NAME>=<SECONDS>	YF_MCP_CACHE_TTL_<NAME>	各工具的默认值	覆盖某个工具的 TTL。

日志始终写入 stderr，因此在 stdio 模式下，stdout 会留给 JSON-RPC 协议使用。在 INFO 级别下，每次工具调用都会留下单行日志，包含工具名称、 答案大小、耗时以及结果缓存是否命中，例如 get_history SAP.DE 250 rows, truncated, 412 ms。调用 失败时会记录一条 WARNING，注明错误类别；Yahoo 限流时也一样。通过 HTTP 发出的请求若被拒绝（状态码 400 及以上，包括 401 和 421）， 日志会记录发起请求的地址。DEBUG 还会记录每个已响应的请求。 日志中绝不会包含 bearer token、搜索查询、URL 的查询字符串、Yahoo 返回的数据或 错误消息文本。

每行都会简短标明来源：server、tools、yahoo、cache、 uvicorn（uvicorn 的服务日志）和 http（请求）；时间采用 ISO 8601 格式，精确到毫秒并带偏移量，例如 2026-09-30T13:19:02.840+02:00 INFO tools: get_quote AAPL 312 ms。时间为机器的本地时间。容器中的时间为 UTC（+00:00），除非你设置 TZ，例如 TZ=Europe/Berlin。在终端中，日志行会带颜色； 设置 NO_COLOR 可关闭颜色。其他场景下（例如容器日志），每 行都是纯文本。

Bearer token（可选）。 设置 YF_MCP_BEARER_TOKEN 后，每个 HTTP 请求 都必须携带 Authorization: Bearer <token>。其他情况都会返回 HTTP 401。 默认关闭，因为通常服务运行在使用它的机器的环回地址上，在这种情况下，token 起不到保护作用。它是一个以恒定时间进行比较的共享密钥，不是 OAuth 流程——只需判断调用方是否符合预期。stdio 会忽略此设置：该进程由客户端管理，其他对象无法访问它。

token 并不能让对外开放的端口变得安全。这里的数据是公开且只读的，因此现实中的风险是有人消耗你的 Yahoo 限流额度，而不是读取私密内容。在可信网络之外使用时，应在前面部署带有真正身份验证的反向代理。 Host 请求头 / DNS 重绑定防护。 MCP HTTP 传输会验证 Host 请求头。绑定到 localhost 时，会启用保护性允许列表 （localhost/127.0.0.1）。绑定到 暴露地址（0.0.0.0）时，默认接受任意 Host 请求头，因此容器和其他主机开箱即用即可访问。若要重新收紧限制，请设置 --allowed-hosts（例如 benethos-yahoo-finance-mcp:8000）—— Host 不在列表中的客户端会收到 HTTP 421。--allowed-origins 也可以单独使用；如果只提供其中一个列表，另一个列表会据此生成。containers/ 中的两个 compose 文件都会为你设置此列表： localhost:*,127.0.0.1:*,[::1]:*,benethos-yahoo-finance-mcp:*。如果不设置，攻击者将网页域名指向 127.0.0.1 后，该网页就能在主机上的浏览器中调用所有工具。 添加前置代理使用的名称。

Docker

已发布的镜像是启动服务的最简途径——无需安装 Python、克隆仓库或构建。每个版本都会推送到 GitHub Container Registry，支持 linux/amd64 和 linux/arm64：

docker run --rm -p 8000:8000 ghcr.io/benethos-hub/benethos-yahoo-finance-mcp:latest
# Server is now reachable at http://localhost:8000/mcp

对于任何依赖项，请固定版本：使用 :0.8.8 指定确切版本，或使用 :0.8 跟随该版本的补丁更新。:latest 会随每次发布而更新，:edge 则按需从 main 构建，并不属于正式版本。

镜像沿用 PyPI 发行包的名称，0.4.0 及之后的每个版本都可以使用该名称获取。直到 0.7.1，镜像都以 ghcr.io/benethos-hub/yahoo-finance-mcp 为名称发布，这些版本也以相同的摘要复制到了新名称下。0.7 系列也以旧名称推送过，镜像仍是同一个。自 0.8.0 起，只有新名称会发布版本。

镜像通过可流式传输的 HTTP 传输方式提供服务。stdio 传输方式用于本地子进程，不适合容器化。

依赖项通过 uv 从 uv.lock 可复现地安装，基础镜像也按摘要固定，因此重新构建相同的提交会得到相同的字节内容。

镜像完全通过环境变量配置（请参阅上方的选项表）——镜像不携带默认命令行参数，因此使用 -e 覆盖单个设置不会影响其他设置。

# Build it yourself instead of pulling (e.g. to run an unreleased main),
# from the repository root
docker build -f containers/images/yahoo-finance-mcp/Dockerfile -t benethos-yahoo-finance-mcp .

# Run with the built-in defaults (streamable-HTTP on 0.0.0.0:8000)
docker run --rm -p 8000:8000 benethos-yahoo-finance-mcp
# Server is now reachable at http://localhost:8000/mcp

# Override settings via -e, opt into the cache and persist it in a named volume
docker run --rm -p 9000:9000 \
    -e YF_MCP_PORT=9000 \
    -e YF_MCP_LOG_LEVEL=DEBUG \
    -e YF_MCP_CACHE=1 \
    -v benethos-yahoo-finance-mcp-cache:/cache \
    benethos-yahoo-finance-mcp

镜像以非 root 用户运行，并在配置的 HTTP 端口上包含健康检查。健康检查会从 YF_MCP_PORT 读取端口，因此应使用 -e YF_MCP_PORT=9000 更改端口，而不是追加 --port 9000，否则容器会一直处于不健康状态。默认情况下，缓存处于关闭状态。使用 -e YF_MCP_CACHE=1 启用缓存后，缓存会写入 /cache（该路径声明为卷）——在此处挂载一个命名卷，即可在容器重启后保留缓存。如需要求每个请求都携带承载令牌，请将 YF_MCP_BEARER_TOKEN=... 写入 .env（请参阅 containers/production/.env.example），然后传入 --env-file .env。也可以使用 -e YF_MCP_BEARER_TOKEN=...，但密钥会留在 shell 历史记录中。在可信网络之外，应在服务前端部署一个负责身份验证的反向代理。除非另行设置，否则 Docker 会无限制地保留容器日志。因此，对于需要长期运行的 docker run，请添加 --log-opt max-size=10m --log-opt max-file=5，或者在守护进程的 log-opts 中统一设置，让所有容器都使用相同配置。

与 compose 文件一样，当容器获得可写的 /tmp 和位于主目录中的可写 yfinance 缓存时，它会以只读根文件系统运行。如果没有后者，yfinance 会静默放弃使用其 Cookie 和时区缓存，并在每次请求时重新查询 Yahoo：

docker run --rm -p 8000:8000 --read-only --tmpfs /tmp \
    --tmpfs /home/appuser/.cache:uid=10001,gid=10001,mode=0700 \
    --cap-drop ALL --security-opt no-new-privileges:true \
    ghcr.io/benethos-hub/benethos-yahoo-finance-mcp:latest

服务需要一个可解析的主目录，因为 yfinance 会在那里保存自己的小型缓存，并在导入时立即查找该目录。镜像中的用户有自己的主目录，而 Docker 和 Kubernetes 会为任何其他 UID 设置 HOME=/，因此在常见配置中无需进行任何操作。如果你以没有 passwd 条目的 UID 运行服务，并且移除了 HOME（加固后的 Pod 规范或 systemd 单元都可能这样做），服务会在启动时停止，并显示 could not determine the home directory。设置 HOME 或绝对路径的 XDG_CACHE_HOME 后，服务即可启动。

Docker Compose

两个 Compose 文件分别位于 containers/ 下各自的文件夹中：

文件夹	用途	镜像	端口
containers/production/	运行已发布的服务，无需克隆	.env 中指定版本的 ghcr.io/benethos-hub/benethos-yahoo-finance-mcp	127.0.0.1:8000，启用 https 配置时，Caddy 使用 80 和 443 端口
containers/development/	尝试更改；运行尚未发布的 main 的唯一方式	基于此检出版本构建	127.0.0.1:8001

要运行服务，请将生产文件夹中的三个文件拉取到一个空文件夹中，并在那里启动：

mkdir yahoo-finance-mcp && cd yahoo-finance-mcp
for file in compose.yaml Caddyfile .env.example; do
  curl -fsSL -o "$file" "https://raw.githubusercontent.com/benethos-hub/yahoo-finance-mcp/main/containers/production/$file"
done
cp .env.example .env      # names the version, set the token here too
docker compose up -d      # pull (if needed) and start in the background
docker compose logs -f    # follow logs
docker compose down       # stop and remove

随后即可通过 http://localhost:8000/mcp 访问服务。 .env 中的 YAHOO_FINANCE_MCP_VERSION 指定镜像版本，且没有默认值，因此执行拉取时版本不会自动改变。要更新，请在其中设置新版本，然后运行 docker compose pull && docker compose up -d。从检出版本构建时，在 containers/development/ 中运行 docker compose up -d --build，即可构建服务并在 8001 端口启动。两个项目名称不同，因此可以同时运行，且各自使用独立的缓存卷。需要 Docker Compose 2.24 或更高版本。

端口仅发布在 127.0.0.1 上，因此服务可从主机访问，但无法从网络中的其他设备访问。这是有意为之，因为除非设置了 YF_MCP_BEARER_TOKEN，否则服务没有身份验证。若要将服务公开，请从 ports: 条目中移除 127.0.0.1: 前缀，至少设置令牌，并在前面放置带身份验证的反向代理。如果主机端口已被占用，请在 .env 中设置 YAHOO_FINANCE_MCP_PORT。

对于其他机器上的客户端，生产文件夹会一并提供此类代理。设置 COMPOSE_PROFILES=https，并在 .env 中设置 YAHOO_FINANCE_MCP_DOMAIN 和 YF_MCP_BEARER_TOKEN 后，Caddy 会在服务前端通过 80 和 443 端口启动，从 Let's Encrypt、自带 CA 或你提供的文件（YAHOO_FINANCE_MCP_TLS）获取域名证书，并在请求到达服务前拒绝不带 Authorization 标头的请求。服务端口仍绑定在 127.0.0.1 上。详情请参阅containers README。

这两个文件都会以只读根文件系统、无 Linux 权限且启用 no-new-privileges 的方式运行容器，并为 /tmp 和 yfinance 的缓存使用 tmpfs。它们会将 Docker 保留的容器日志限制为 5 个文件，每个 10 MB，优先删除最旧的文件（x-logging）。若要保留更多日志，请调高 max-size 或 max-file。若要将日志保存在其他位置，请更换驱动程序，例如使用 journald，并通过 journalctl CONTAINER_NAME=benethos-yahoo-finance-mcp 读取日志。

密钥应放在 Compose 文件旁的 .env 中；Compose 会通过 env_file 读取此文件，而 git 和 Docker 构建上下文都会忽略它。请在此处设置 YF_MCP_BEARER_TOKEN，不要在 compose.yaml 中设置。Compose 会读取 YAHOO_FINANCE_MCP_VERSION、YAHOO_FINANCE_MCP_PORT 和 COMPOSE_PROFILES，将 YAHOO_FINANCE_MCP_DOMAIN 和 YAHOO_FINANCE_MCP_TLS 传给 Caddy，并将其他所有变量传给服务。在 compose.yaml 的 environment: 下设置的变量名，会覆盖 .env 中同名变量。只有 Compose 会读取此文件。服务本身不会加载它，因此对于普通的 docker run，请传入 --env-file .env；对于本地或 Claude Desktop 配置，请继续使用环境变量。

以前位于仓库根目录的 Compose 文件配置现已迁移到 containers/production/。其项目名称保持不变，因此缓存卷会保留。

手动安装（uv 或 venv）

使用 uv（任何操作系统）：

# Streamable HTTP on http://127.0.0.1:8000/mcp
uv run benethos-yahoo-finance-mcp --transport streamable-http

# Bind all interfaces on a custom port / path
uv run benethos-yahoo-finance-mcp \
    --transport streamable-http --host 0.0.0.0 --port 9000 --path /yf

直接使用 venv 解释器（Windows：.venv\Scripts\python.exe）：

.venv/bin/python -m benethos_yahoo_finance_mcp --transport streamable-http

缓存

选择启用的持久化缓存。启用后，成功的工具结果会缓存到一个较小的 SQLite 文件中，并为每种工具设置生存时间（TTL），以减轻 Yahoo 端点的负载并在重启后保留缓存。变化较快的数据 TTL 较短，稳定的数据 TTL 较长。

每次调用都会重新向 Yahoo 请求数据；缓存可以让重复请求成本更低，并在重启后继续生效，同时提供速率限制保护。默认关闭，因为通常是在 stdio 上进行交互式会话，重复请求较少，而且新鲜数据更重要；此外，是否在磁盘上保存文件也由操作者决定。

缓存名称（用于 --cache-ttl <NAME>=<SECONDS> 和 YF_MCP_CACHE_TTL_<NAME>）及其默认 TTL：

名称	工具	默认 TTL
quote	get_quote	30 s
quotes	get_quotes	30 s
history	get_history	10 min
news	get_news	10 min
options	get_options	10 min
screen	screen	10 min
search	search	1 h
company_info	get_company_info	6 h
dividends	get_dividends	6 h
recommendations	get_recommendations	6 h
earnings	get_earnings	6 h
estimates	get_estimates	6 h
upgrades_downgrades	get_upgrades_downgrades	6 h
insider_activity	get_insider_activity	6 h
sec_filings	get_sec_filings	6 h
calendar	get_calendar	6 h
financials	get_financials	24 h
holders	get_holders	24 h
shares	get_shares	24 h
fund_data	get_fund_data	24 h
sector	get_sector	24 h
industry	get_industry	24 h
market	get_market	60 s

• 默认关闭。使用 --cache 或 YF_MCP_CACHE=1 启用。
• 位置：操作系统的用户缓存目录，或通过 --cache-dir / YF_MCP_CACHE_DIR 指定。 文件大小会随缓存内容增加，并在清理过期条目后再次缩小。由早期版本创建的文件会在启动时重写一次。
• 大小：最多 10 000 条目，保留最近写入的条目；使用 --cache-max-entries / YF_MCP_CACHE_MAX_ENTRIES 设置。
• 覆盖 TTL：使用 --cache-ttl quote=15（可重复指定），或设置 YF_MCP_CACHE_TTL_<NAME> 环境变量（例如 YF_MCP_CACHE_TTL_QUOTE=15）。 将 TTL 设为 0 可绕过该工具的缓存。

优先级为 CLI > 环境变量 > 默认值。错误永不缓存，缓存故障也不会导致调用失败：如果缓存文件被锁定或损坏，会记录日志，并像关闭缓存一样获取数据。

何时启用

如果你符合以下情况，请启用缓存（--cache / YF_MCP_CACHE=1）：

• 将服务作为长时间运行或容器化的 HTTP 服务运行，并定期重启（缓存会在重启后保留 → 重复请求可立即返回结果）。
• 遇到 Yahoo 速率限制，或长期反复发出许多相同请求。
• 主要查询变化缓慢的数据（搜索、公司信息、财务数据），此时数据陈旧无关紧要。

如果你符合以下情况，请保持关闭（默认设置）：

• 在本地通过 stdio 进行交互式会话——几分钟内重复询问同一个问题的情况很少见，而且新鲜数据更重要。
• 需要尽可能最新的数据。
• 只是偶尔使用。

开发

有关代码如何按模块组织，请参阅 SPECS.md。

安装开发扩展，然后运行测试、代码检查和类型检查步骤（与 CI 运行的步骤相同）。

使用 uv（适用于任何操作系统）：

uv sync --extra dev

uv run pytest -q                 # unit tests (offline)
uv run ruff check .              # lint
uv run ruff format .             # format
uv run mypy                      # type check
uv run pytest --cov=benethos_yahoo_finance_mcp   # coverage

直接使用 venv 解释器（在 Windows 上将 .venv/bin/python 替换为 .venv\Scripts\python.exe）：

.venv/bin/python -m pip install -e ".[dev]"

.venv/bin/python -m pytest -q                 # unit tests (offline)
.venv/bin/python -m ruff check .              # lint
.venv/bin/python -m ruff format .             # format
.venv/bin/python -m mypy                      # type check
.venv/bin/python -m pytest --cov=benethos_yahoo_finance_mcp   # coverage

单元测试会模拟 yfinance，并完全离线运行。tests/smoke.py 会针对实时 Yahoo Finance 执行一次临时检查，不属于单元测试套件。 CI 还会在 Python 3.11–3.15 上运行，并强制要求覆盖率至少达到 80%， 覆盖率在 3.15 上测量；上方的覆盖率徽章显示了该运行在 main 上测得的结果。另外还有两个任务不使用锁文件安装：fresh-install 使用 pyproject.toml 允许的最新版本，lowest-versions 使用最低版本。uv.lock 中的每个版本以及每个最低版本都会针对 PyPI 和 OSV 检查已知漏洞。

商标

“Yahoo”和“Yahoo Finance”是 Yahoo Inc. 的商标。本项目与 Yahoo 无关，也未获得其认可或赞助，并非 Yahoo 的官方产品。

此处使用这些名称，仅用于说明软件的功能，即通过 yfinance 库读取 Yahoo Finance 的市场数据。这是唯一准确的表述。所有商标均为各自所有者的财产。

本项目以 benethos-yahoo-finance-mcp 的名称发布，并依据 MIT 许可证 独立维护。