Yahoo Finance unofficial MCP Server

YFinance MCP 服务

一个全面的模型上下文协议（MCP）服务，通过集成 Yahoo Finance API 提供金融数据。此服务使 AI Agent 能够访问实时股票市场数据、历史价格、财务报表和市场分析。

功能

• 10 种全面的金融工具，用于获取完整的市场数据
• 实时股票信息，包括价格、市值和关键指标
• 历史数据分析，支持灵活的时间段和间隔
• 财务报表（利润表、资产负债表、现金流量表）
• 收益数据（年度和季度）
• 股息和拆股历史记录
• 新闻和分析师建议
• 股票搜索和多股票报价支持
• 健壮的错误处理，返回结构化 JSON 响应
• FastMCP 框架，支持异步处理，性能出色

快速开始

先决条件

• Python 3.11+
• uv（Python 包管理器）

安装

# Clone the repository
git clone https://github.com/barvhaim/yfinance-mcp-server.git
cd yfinance-mcp-server

# Install dependencies
uv sync

运行服务

# Start the MCP server
uv run main.py

# The server will start and be ready to accept MCP client connections

可用工具

1. get_stock_info

获取全面的股票信息，包括当前价格、市值和财务指标。

参数：

• symbol（str）：股票代码（例如，'AAPL'、'GOOGL'）

返回： 股票信息，包括价格、市值、市盈率、股息收益率、52 周区间、成交量、贝塔值和公司详情。

2. get_historical_data

按灵活的时间段和间隔检索历史股票价格数据。

参数：

• symbol（str）：股票代码
• period（str）：时间段（1d、5d、1mo、3mo、6mo、1y、2y、5y、10y、ytd、max）
• interval（str）：数据间隔（1m、2m、5m、15m、30m、60m、90m、1h、1d、5d、1wk、1mo、3mo）

返回： 包含日期和成交量信息的历史 OHLCV 数据。

3. get_dividends

获取股票的股息支付历史记录。

参数：

• symbol（str）：股票代码

返回： 包含日期和金额的股息支付列表。

4. get_splits

检索股票拆股历史记录。

参数：

• symbol（str）：股票代码

返回： 包含日期和拆股比例的股票拆股列表。

5. get_financials

获取全面的财务报表。

参数：

• symbol（str）：股票代码
• quarterly（bool）：若为 True，则获取季度数据；若为 False，则获取年度数据

返回： 利润表、资产负债表和现金流量表数据。

6. get_earnings

检索用于分析的收益数据。

参数：

• symbol（str）：股票代码

返回： 年度和季度收益数据。

7. get_news

获取与股票相关的近期新闻文章。

参数：

• symbol（str）：股票代码
• count（int）：要返回的文章数量（默认值：10）

返回： 新闻文章列表，包含标题、链接、发布方和时间戳。

8. get_recommendations

获取分析师建议和评级。

参数：

• symbol（str）：股票代码

返回： 分析师建议列表，包含公司、评级和操作。

9. search_stocks

按公司名称或股票代码搜索股票。

参数：

• query（str）：搜索查询（公司名称或股票代码）
• limit（int）：最多返回的结果数（默认值：10）

返回： 匹配的股票列表，包含代码、名称和交易所信息。

10. get_multiple_quotes

同时获取多只股票的当前报价。

参数：

• symbols（List[str]）：股票代码列表

返回： 股票报价字典，包含当前价格、变动和基本指标。

使用示例

基本股票信息

# Get Apple stock information
result = await get_stock_info("AAPL")
print(f"Current Price: ${result['current_price']}")
print(f"Market Cap: ${result['market_cap']:,}")

历史数据分析

# Get 1-year daily data for Google
result = await get_historical_data("GOOGL", period="1y", interval="1d")
print(f"Retrieved {result['count']} data points")

多只股票报价

# Get quotes for tech stocks
result = await get_multiple_quotes(["AAPL", "GOOGL", "MSFT", "AMZN"])
for symbol, quote in result['quotes'].items():
    print(f"{symbol}: ${quote['current_price']}")

MCP 客户端集成

Claude Desktop 集成

要将此服务连接到 Claude Desktop：

1. 在一个终端中启动服务：

   uv run main.py
   

2. 编辑 MCP 设置文件来配置 Claude Desktop：

   macOS：~/Library/Application Support/Claude/claude_desktop_config.json

   Windows：%APPDATA%\Claude\claude_desktop_config.json

3. 添加服务配置：

   {
      "yfinance": {
        "command": "uv",
        "args": [
          "--directory",
          "/path/to/yfinance-mcp-server",
          "run",
          "main.py"
        ]
      }
    }
   

4. 将 cwd 路径更新为你的实际项目目录

5. 重启 Claude Desktop 以加载新服务

6. 询问 Claude：“你有哪些可用的金融数据工具？”，以验证连接

替代方案：直接连接

对于其他 MCP 客户端：

1. 启动服务：uv run main.py
2. 配置 MCP 客户端，使其连接到服务端点
3. 你的 AI Agent 将自动发现工具
4. 使用这些工具处理标准股票代码（AAPL、GOOGL、MSFT 等）

开发

代码格式化

# Format code with black
uv run black .

# Check formatting
uv run black --check .

# Show formatting differences
uv run black --diff .

添加新工具

1. 在 main.py 中创建一个新的异步函数
2. 使用 @mcp.tool() 装饰
3. 添加合适的类型提示和文档字符串
4. 添加错误处理
5. 测试实现

环境变量

如需进行配置，请将 .env.sample 复制为 .env：

cp .env.sample .env

错误处理

所有工具都包含全面的错误处理：

• 无效代码会返回结构化错误消息
• 网络问题会被捕获并报告
• 数据不可用时会妥善处理
• yfinance 会自动遵守速率限制

性能注意事项

• 使用异步操作以获得最佳性能
• 使用结构化 JSON 进行高效的数据序列化
• 通过尽量减少数据处理来降低延迟
• yfinance 会对频繁访问的数据进行内置缓存

依赖项

• fastmcp - 用于实现 MCP 服务的 FastMCP 框架
• yfinance - 用于获取金融数据的 Yahoo Finance API
• python-dotenv - 环境变量管理
• black - 代码格式化
• pydantic - 数据验证和序列化

许可证

此项目采用 MIT 许可证。

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 视情况添加测试
5. 使用 black 格式化代码
6. 提交拉取请求

支持

如有问题，请：

• 查看 Issues 部分
• 查阅 CLAUDE.md 文件中的开发指南
• 使用 uv sync 确保已正确安装所有依赖项

更新日志

v0.1.0

• 初始实现，包含 10 个金融数据工具
• 集成 FastMCP 服务框架
• 全面的错误处理
• 完整支持 yfinance API
• 支持 MCP 客户端集成