Yahoo Finance MCP Server

Yahoo Finance MCP 服务

一个 Model Context Protocol (MCP) 服务，通过 yfinance 为 AI 助手提供 Yahoo Finance 数据访问能力。查询股票信息、财经新闻、行业排名，还能生成专业的金融图表——一切尽在 AI 聊天中。

功能

• 股票数据 — 公司信息、财务数据、估值指标、股息和交易数据
• 分析师数据 — 共识目标价、预测／修正趋势、评级历史和机构操作
• 财务报表 — 包含历史数据的损益表和资产负债表（EBIT、投入资本等）
• 财经新闻 — 任意股票代码的近期新闻文章和新闻稿
• 搜索 — 在 Yahoo Finance 中查找股票、ETF 和新闻
• 行业排名 — 按行业查看顶级 ETF、共同基金、公司、增长领先者和表现最佳者
• 价格历史 — 以 Markdown 表格或专业图表形式呈现历史 OHLCV 数据
• 图表生成 — 生成蜡烛图、VWAP 和成交量分布图，并以 WebP 图片形式返回
• 期权数据 — 期权链，包含看涨期权、看跌期权、行权价、IV 和到期日
• 持有者数据 — 主要持有者、机构投资者、共同基金持有者和内部人交易
• 基金穿透分析 — ETF 和共同基金的持仓、资产类别、行业、评级和运营详情
• 筛选器 — 预定义筛选器、股票、共同基金和 ETF 查询树

工具

yfinance_get_ticker_info

获取全面的股票数据，包括公司信息、财务数据、交易指标和治理数据。

参数	类型	必填	说明
symbol	string	是	股票代码（例如 AAPL、GOOGL、MSFT）

**返回：**包含公司详情、价格数据、估值指标、交易信息、股息、财务数据和业绩指标的 JSON 对象。

yfinance_get_analyst_price_targets

获取当前股价和分析师对该股票的一致目标价。

参数	类型	必填	说明
symbol	string	是	股票代码（例如 AAPL、GOOGL、MSFT）

**返回：**包含 current、low、high、mean 和 median 价格字段的 JSON 对象。分析师覆盖情况和可用字段因股票代码而异。

yfinance_get_analyst_estimates

获取分析师共识预测、修正动向、评级、增长预测和盈利历史。

参数	类型	必填	说明
symbol	string	是	股票代码
sections	array	否	可选值为 recommendations、earnings_estimate、revenue_estimate、eps_trend、eps_revisions、earnings_history 或 growth_estimates。省略则返回所有部分
max_rows	number	否	每个部分的最大行数。默认值：12。使用 0 可返回所有行

**返回：**包含可用部分命名数组的对象，以及 _metadata，其中包含每个部分的行数、截断状态、不可用部分和失败部分。某个部分获取失败不会影响已成功获取的部分。

yfinance_get_upgrades_downgrades

获取分析师评级上调、下调、首次评级、重申评级和目标价变更记录，按时间从新到旧排列。

参数	类型	必填	描述
symbol	string	是	股票代码
max_rows	number	否	返回的操作记录数量上限。默认值：25。设为 0 可返回所有记录

**返回：**包含 upgrades_downgrades 记录以及 _metadata 的 JSON 对象；_metadata 包含行数和截断状态。记录可能包含：

• GradeDate：分析师操作的日期和时间
• Firm：分析师所属机构名称
• ToGrade 和 FromGrade：新评级和先前评级
• Action：评级操作
• priceTargetAction：目标价操作，例如 Raises、Lowers 或 Maintains
• currentPriceTarget 和 priorPriceTarget：新目标价和先前目标价

可用字段因股票代码和分析师操作而异。

yfinance_get_ticker_news

获取特定股票的最新新闻文章和新闻稿。

参数	类型	必填	描述
symbol	string	是	股票代码

symbol 必须非空，且只能包含 ASCII 字母、数字或 ., -, ^, =, &, _。 输入无效时会返回 INVALID_PARAMS，不会回显输入内容，也不会调用 Yahoo Finance。 接受的格式包括 BRK.B、2330.TW、^GSPC、EURUSD=X、ES=F 和 BTC-USD。 此格式检查不会验证股票代码是否存在。

**返回：**包含新闻条目的 JSON 数组，条目包含标题、摘要、发布日期、提供方、URL 和缩略图。

yfinance_search

在 Yahoo Finance 中搜索股票、ETF 和新闻文章。

参数	类型	必填	描述
query	string	是	搜索查询——公司名称、股票代码或关键词
search_type	string	是	"all"（行情 + 新闻）、"quotes"（仅股票/ETF）或 "news"（仅文章）

**返回：**根据 search_type 返回匹配的行情和/或新闻结果。

yfinance_get_top

获取市场板块内排名靠前的金融实体。

参数	类型	必填	描述
sector	string	是	市场板块（见下文的支持的板块）
top_type	string	是	"top_etfs"、"top_mutual_funds"、"top_companies"、"top_growth_companies" 或 "top_performing_companies"
top_n	number	否	返回结果数量（默认值：10，最大值：100）

**返回：**包含相关指标的排名靠前实体 JSON 数组。

支持的板块

Basic Materials、Communication Services、Consumer Cyclical、Consumer Defensive、Energy、Financial Services、Healthcare、Industrials、Real Estate、Technology、Utilities

yfinance_screen

使用预定义筛选器键或自定义查询树运行 Yahoo Finance 筛选器。

参数	类型	必填	描述
query	string/object	是	对于 query_type="predefined"：筛选器键，例如 "day_gainers"。对于 query_type="equity"、"fund" 或 "etf"：包含 {operator, operands} 节点的自定义查询树
query_type	string	否	"predefined"（默认）、"equity"、"fund" 或 "etf"
offset	number	否	结果偏移量
size	number	否	自定义查询的行数；Yahoo 上限为 250
count	number	否	预定义查询的行数；Yahoo 上限为 250
sort_field	string	否	排序字段，例如 "percentchange"
sort_asc	boolean	否	true 时按升序排序，false 时按降序排序
user_id	string	否	可选的 Yahoo 用户标识符
user_id_type	string	否	可选的 Yahoo 用户 ID 类型，通常为 "guid"

返回： 来自 Yahoo Finance 的 JSON 筛选器响应，通常包含报价行和元数据。

自定义股票筛选器示例：

{
  "query_type": "equity",
  "query": {
    "operator": "and",
    "operands": [
      { "operator": "gt", "operands": ["percentchange", 3] },
      { "operator": "eq", "operands": ["region", "us"] },
      { "operator": "gte", "operands": ["intradayprice", 5] },
      { "operator": "gt", "operands": ["dayvolume", 500000] }
    ]
  },
  "sort_field": "percentchange",
  "sort_asc": false,
  "size": 50
}

自定义 ETF 筛选器示例：

{
  "query_type": "etf",
  "query": {
    "operator": "and",
    "operands": [
      { "operator": "eq", "operands": ["categoryname", "Large Blend"] },
      { "operator": "lte", "operands": ["annualreportnetexpenseratio", 0.2] }
    ]
  },
  "sort_field": "fundnetassets",
  "sort_asc": false,
  "size": 25
}

yfinance_screen_gappers

运行专门用于筛选开盘时段看涨跳空股票的自定义筛选器。

参数	类型	必填	描述
min_percent_change	number	否	相对于前收盘价的最低跳空／涨跌幅（默认值：3.0）
min_price	number	否	最低日内价格（默认值：5.0）
min_volume	number	否	最低当日成交量（默认值：500000）
min_market_cap	number	否	最低日内市值，单位为美元（默认值：2000000000）
region	string	否	Yahoo 区域代码（默认值："us"）
size	number	否	结果数量（默认值：50，上限：250）
offset	number	否	分页结果偏移量（默认值：0）
sort_asc	boolean	否	按 percentchange 升序（true）或降序（false，默认值）排序

返回： 来自 Yahoo Finance 的 JSON 筛选器响应。

yfinance_get_price_history

获取历史价格数据，并可选择生成技术分析图表。

参数	类型	必填	描述
symbol	string	是	股票代码
period	string	否	时间范围 — 1d、5d、1mo、3mo、6mo、1y、2y、5y、10y、ytd、max（默认值：1mo）
interval	string	否	数据粒度 — 1m、2m、5m、15m、30m、60m、90m、1h、1d、5d、1wk、1mo、3mo（默认值：1d）
chart_type	string	否	要生成的图表（省略则返回表格数据）
prepost	boolean	否	在可用时包含盘前和盘后数据（默认值：false；适用于 period="1d"、interval="1m" 等日内请求）

图表类型：

值	描述
"price_volume"	带成交量柱的蜡烛图
"vwap"	带成交量加权平均价叠加线的价格图
"volume_profile"	按价格水平显示成交量分布的蜡烛图

返回：

• 不指定 chart_type：Markdown 表格，包含 Date、Open、High、Low、Close、Volume、Dividends 和 Stock Splits 列。
• 指定 chart_type：经 Base64 编码的 WebP 图像，可高效利用 token。

yfinance_get_financials

获取包含历史数据的财务报表（损益表、资产负债表和现金流量表）。

参数	类型	必填	说明
symbol	string	是	股票代码
frequency	string	否	"annual"（年度）、"quarterly"（季度）或 "ttm"（过去 12 个月）。默认值："annual"

返回： JSON 对象，包含各报告期的损益表、资产负债表和现金流量数据。

• 损益表字段：EBIT、净利润、税项、税前利润、利息支出、总收入、营业收入、EBITDA、标准化净利润
• 资产负债表字段：股东权益、总债务、现金及现金等价物、投入资本、净债务、总资产、负债合计（含少数股东权益）、净有形资产、有形账面价值
• 现金流量表字段：经营活动现金流、自由现金流、资本支出、持续经营业务净利润、折旧与摊销、营运资本变动、已支付现金股利

yfinance_get_holders

获取主要持有人、机构持有人、共同基金持有人和内部人士数据。

参数	类型	必填	说明
symbol	string	是	股票代码（例如 AAPL、MSFT）
max_rows	number	否	每个持有人类别返回的最大行数。默认值：10。使用 0 返回全部行

返回： JSON 对象，包含：

• major_holders — 汇总持有人明细，每行包含一个 index 标签（例如 insidersPercentHeld、institutionsPercentHeld、institutionsFloatPercentHeld、institutionsCount）和一个 Value
• institutional_holders — 机构投资者；记录通常包含 Date Reported、Holder、Shares、Value、pctChange、pctHeld 等字段
• mutualfund_holders — 共同基金持有人；记录通常包含与机构持有人类似的字段
• insider_transactions — 近期内部人士交易；记录通常包含 Shares、Value、Insider、Position、Transaction、Start Date、Ownership 等字段
• insider_purchases — 六个月汇总，每行描述一个类别（购买、出售、净股数等）；记录通常包含 Insider Purchases Last 6m、Shares、Trans 等字段
• insider_roster — 已知内部人士；记录通常包含 Name、Position、Shares Owned Directly、Most Recent Transaction、Latest Transaction Date 等字段
• _metadata — 行数限制元数据，包含 max_rows 以及各类别的 total_rows、returned_rows 和 truncated

默认情况下，持有人类别最多返回 10 行，以使响应简洁。需要完整的持有人数据集时，请传入 max_rows: 0。持有人相关数据集的字段名称由 yfinance 提供，可能因股票代码、数据可用性和 yfinance 版本而异。

yfinance_get_fund_data

获取 ETF 或共同基金的投资组合构成和运营详情。

参数	类型	必填	说明
symbol	string	是	ETF 或共同基金代码（例如 SPY、BND 或 VFIAX）
sections	array	否	可选值为 description、fund_overview、fund_operations、asset_classes、top_holdings、equity_holdings、bond_holdings、bond_ratings 或 sector_weightings。省略时返回所有类别
max_rows	number	否	每个表格类别返回的最大行数。默认值：25。使用 0 返回全部行

返回： 可用的基金类别，以及包含行数限制、各类别截断情况、不可用类别和失败类别的 _metadata。类别组合取决于基金类型；例如，股票基金和债券基金会提供不同的投资组合明细。

yfinance_get_option_dates

获取股票可用的期权到期日期。

Parameter	Type	Required	Description
symbol	string	是	股票代码（例如 AAPL、MSFT）

返回： YYYY-MM-DD 格式的到期日期 JSON 数组。

yfinance_get_option_chain

获取股票的期权链数据（看涨期权和看跌期权），以及可用的行权价。

Parameter	Type	Required	Description
symbol	string	是	股票代码
expiration_date	string	否	YYYY-MM-DD 格式的期权到期日期。省略则获取所有日期。
option_type	string	否	"calls"、"puts" 或 "all"（默认值："all"）

返回： 以到期日期为键的 JSON 对象，其中包含看涨期权和/或看跌期权数据，包括：

• contractSymbol：期权合约标识符
• strike：行权价
• lastPrice：最新成交价
• bid/ask：买入价和卖出价
• volume：交易量
• openInterest：未平仓合约数
• impliedVolatility：隐含波动率（IV）
• inTheMoney：期权是否处于实值状态
• contractSize：合约规模（REGULAR）
• currency：货币（USD）

使用方法

通过 uv（推荐）

1. 安装 uv
2. 将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "yfmcp": {
      "command": "uvx",
      "args": ["yfmcp@latest"]
    }
  }
}

通过 Docker

{
  "mcpServers": {
    "yfmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "narumi/yfinance-mcp"]
    }
  }
}

从源代码安装

1. 克隆仓库并安装依赖项：

git clone https://github.com/narumiruna/yfinance-mcp.git
cd yfinance-mcp
uv sync

2. 将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "yfmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yfinance-mcp",
        "yfmcp"
      ]
    }
  }
}

将 /path/to/yfinance-mcp 替换为克隆仓库的实际路径。

使用 Codex CLI 进行测试

此仓库包含 .codex/config.toml，其中通过 uv run yfmcp 为 Codex CLI 注册了本地 yfmcp MCP 服务。克隆仓库并运行 uv sync 后，从仓库根目录启动 Codex CLI，并尝试以下提示词：

Show VOO ticker info
Show VOO price history for the last 5 days
Find the ticker symbol for Toyota
Get AAPL option expiration dates

开发

前置条件

• Python ≥ 3.12
• uv 包管理器

设置

uv sync --extra dev

检查与格式化

uv run ruff check .
uv run ruff format .

类型检查

uv run ty check src tests

测试

uv run pytest -v -s --cov=src tests

演示聊天机器人

请参阅专属仓库中的演示聊天机器人：yfinance-mcp-demo

贡献者

由 contrib.rocks 制作。

许可证

本项目采用 MIT License 许可。