Name: 金融数据服务
Author: ozp

使用说明

MCP雅虎金融服务器

一个生产就绪的模型上下文协议（MCP）服务器，通过18个专用工具提供对雅虎财经数据的全面访问。具有智能缓存、多市场支持和完全类型安全。

🌟 特性

18个综合工具 -全面报道定价、财务、期权、持有人和新闻
智能SQLite缓存 -通过基于TTL的缓存管理将延迟减少90%
多市场支持 -在全球范围内使用可配置的市场规范化（美国、英国、德国、法国、日本、印度、香港、澳大利亚、加利福尼亚州等）
类型安全 -完整的Pydantic模型，其中包含完整的类型提示
生产准备就绪 -使用自定义异常层次结构进行稳健的错误处理
零配置 -通过以下方式立即部署 uvx 无需设置
异步/等待 -针对并发操作进行了优化

🚀 快速开始

通过uvx安装（推荐）

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "yfinance": {
      "command": "uvx",
      "args": ["mcp-yfinance"],
      "env": {
        "YFINANCE_DEFAULT_MARKET": "US"
      }
    }
  }
}

手动安装

# Install with pip
pip install mcp-yfinance

# Or install from source
git clone https://github.com/yourusername/mcp-yfinance.git
cd mcp-yfinance
pip install -e .

🛠️ 配置

市场选择

通过环境变量设置默认市场：

# US stocks (default)
export YFINANCE_DEFAULT_MARKET=US

# Brazilian stocks (auto-adds .SA suffix)
export YFINANCE_DEFAULT_MARKET=BR

# UK stocks (auto-adds .L suffix)
export YFINANCE_DEFAULT_MARKET=UK

# Indian stocks - NSE (auto-adds .NS suffix)
export YFINANCE_DEFAULT_MARKET=IN_NSE

# Indian stocks - BSE (auto-adds .BO suffix)
export YFINANCE_DEFAULT_MARKET=IN_BSE

支持的市场：

US -美国（无后缀）
BR -巴西（.SA）
UK -英国（.L）
DE -德国（.DE）
FR -法国（.PA）
JP -日本（.T）
IN_NSE -印度NSE（.NS）
IN_BSE -印度BSE（.BO）
HK -香港（.HK）
AU -澳大利亚（.AX）
CA -加拿大（.TO）

缓存配置

缓存在以下位置自动创建 ~/.mcp-yfinance/cache.db 具有以下TTL：

数据类型	TTL	用例
当前报价	5分钟	实时价格跟踪
期权链	5分钟	期权交易
新闻	30分钟	最近的新闻更新
库存信息	1小时	公司信息
历史数据	24小时	价格历史
财务报表	24小时	季度/年度报告
持有人	24小时	所有权数据
建议	24小时	分析师评级

📚 可用工具

定价和历史数据（6个工具）

1. `get_current_stock_price`

获取当前股票价格和日变化信息。

输入：

{
  "symbol": "AAPL"
}

输出：

{
  "symbol": "AAPL",
  "price": 234.56,
  "change": 2.34,
  "change_percent": 1.01,
  "volume": 52487900,
  "currency": "USD",
  "timestamp": "2025-01-15T16:00:00"
}

2. `get_stock_price_by_date`

获取特定日期的收盘价。

输入：

{
  "symbol": "MSFT",
  "date": "2025-01-10"
}

3. `get_stock_price_date_range`

获取日期范围的价格系列。

输入：

{
  "symbol": "GOOGL",
  "start_date": "2025-01-01",
  "end_date": "2025-01-15"
}

4. `get_historical_stock_prices`

获取完整的OHLCV（开盘、高、低、收盘、成交量）历史数据。

输入：

{
  "symbol": "TSLA",
  "period": "1mo",
  "interval": "1d"
}

支持的时段： 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max

支持的时间间隔： 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo

5. `get_dividends`

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

6. `get_stock_actions`

获取所有股票操作（股息+分割）。

公司信息（1个工具）

7. `get_stock_info`

获取全面的公司信息（约100个字段）。

输出包括：

公司名称、部门、行业
市值、企业价值
市盈率、股息收益率
52周高点/低点
贝塔，尾随每股收益
还有更多。..

财务报表（3个工具）

8. `get_income_statement`

收入表（DRE）

输入：

{
  "symbol": "AAPL",
  "freq": "yearly"
}

频率： yearly, quarterly, trailing

9. `get_balance_sheet`

获取资产负债表（Balanço Patrimonial）。

10. `get_cashflow`

获取现金流量表。

持有人和所有权（1个工具）

11. `get_holder_info`

获取6种不同类型的持有人信息。

输入：

{
  "symbol": "NVDA",
  "holder_type": "institutional_holders"
}

支架类型：

major_holders -主要所有权百分比
institutional_holders -机构投资者
mutualfund_holders -共同基金持股
insider_transactions -近期内幕交易
insider_purchases -内幕交易
insider_roster_holders -当前内部人员名单

选项（2个工具）

12. `get_option_expiration_dates`

获取所有可用选项的到期日期。

输出：

["2025-01-17", "2025-01-24", "2025-02-21", ...]

13. `get_option_chain`

获取特定到期日期的期权链。

输入：

{
  "symbol": "SPY",
  "expiration_date": "2025-01-17",
  "option_type": "both"
}

选项类型： calls, puts, both

输出包括：

合同符号
执行价格
最后价格、出价、要价
交易量和未平仓合约
隐含波动率

新闻与分析（5个工具）

14. `get_news`

获取最近的新闻文章。

输出：

[
  {
    "title": "Apple announces new iPhone",
    "summary": "...",
    "url": "https://...",
    "provider": "Reuters",
    "publishedAt": "2025-01-15T10:30:00Z"
  }
]

15. `get_recommendations`

获取分析师建议和升级/降级。

输入：

{
  "symbol": "TSLA",
  "recommendation_type": "upgrades_downgrades",
  "months_back": 12
}

推荐类型： recommendations, upgrades_downgrades

16. `get_earning_dates`

获取收益公告日期（过去和未来）。

输入：

{
  "symbol": "META",
  "limit": 12
}

17. `get_stock_splits`

获取历史股票分割数据。

输入：

{
  "symbol": "AAPL"
}

输出：

[
  {
    "date": "2020-08-31",
    "ratio": 4.0
  },
  {
    "date": "2014-06-09",
    "ratio": 7.0
  }
]

18. `get_analyst_price_targets`

获取分析师的价格目标和估计。

输入：

{
  "symbol": "NVDA"
}

输出包括：

当前价格
目标均值、中位数、高、低
分析师人数
推荐（买入/持有/卖出）

💡 使用示例

使用克劳德桌面

User: What's the current price of Apple stock?
Claude: [Uses get_current_stock_price tool]
        Apple (AAPL) is currently trading at $234.56, up $2.34 (1.01%) today.

User: Show me Microsoft's quarterly revenue for the last year
Claude: [Uses get_income_statement with freq="quarterly"]
        Here's Microsoft's quarterly revenue...

User: Get Tesla call options expiring next month
Claude: [Uses get_option_expiration_dates, then get_option_chain]
        Here are Tesla's call options for 2025-02-21...

巴西市场示例

{
  "mcpServers": {
    "yfinance-br": {
      "command": "uvx",
      "args": ["mcp-yfinance"],
      "env": {
        "YFINANCE_DEFAULT_MARKET": "BR"
      }
    }
  }
}

User: Qual o preço atual de PETR4?
Claude: [Automatically normalizes to PETR4.SA]
        Petrobras PN (PETR4.SA) está cotada a R$ 38.45...

🏗️ 建筑

┌──────────────────────────────────┐
│   Claude Desktop / API Client    │
│   (User makes stock queries)     │
└────────────┬─────────────────────┘
             │ stdio
┌────────────▼─────────────────────┐
│   server.py (MCP Protocol)       │ ◄─── Tool registration
│   - @server.list_tools()         │      Input validation
│   - @server.call_tool()          │      Response formatting
└────────────┬─────────────────────┘
             │
┌────────────▼─────────────────────┐
│   cache.py (Cache Layer)         │ ◄─── TTL-based caching
│   - Check cache by key           │      5min: quotes
│   - Return if valid              │      1h: stock info
│   - Pass through if miss         │      24h: historical
└────────────┬─────────────────────┘
             │ (cache miss)
┌────────────▼─────────────────────┐
│   service.py (Business Logic)    │ ◄─── YahooFinanceService
│   - Normalize ticker             │      Input validation
│   - Call yfinance                │      Data transformation
│   - Map to Pydantic models       │      Error handling
│   - Save to cache                │      Market normalization
└────────────┬─────────────────────┘
             │
┌────────────▼─────────────────────┐
│   yfinance library               │
│   (Yahoo Finance API)            │
└──────────────────────────────────┘

项目结构

mcp-yfinance/
├── src/
│   └── mcp_yfinance/
│       ├── __init__.py       # Version, exports, main()
│       ├── __main__.py       # CLI entry point
│       ├── server.py         # MCP server orchestration
│       ├── service.py        # Business logic (18 methods)
│       ├── models.py         # Pydantic schemas + Enums
│       ├── cache.py          # SQLite cache manager
│       ├── exceptions.py     # Custom exception hierarchy
│       ├── utils.py          # Helper functions
│       ├── config.py         # Configuration management
│       └── py.typed          # Type checking marker
├── tests/                    # Test suite
├── pyproject.toml           # Package configuration
└── README.md                # This file

🧪 发展

设置开发环境

# Clone repository
git clone https://github.com/yourusername/mcp-yfinance.git
cd mcp-yfinance

# Install with dev dependencies
pip install -e ".[dev]"

# Or with uv (recommended)
uv pip install -e ".[dev]"

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_yfinance --cov-report=html

# Run specific test file
pytest tests/test_service.py

类型检查

# Run mypy
mypy src/mcp_yfinance

# Run ruff (linter + formatter)
ruff check src/mcp_yfinance
ruff format src/mcp_yfinance

测试服务器

# Run server directly
python -m mcp_yfinance

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run mcp-yfinance

# Test with environment variable
YFINANCE_DEFAULT_MARKET=BR python -m mcp_yfinance

🔧 故障排除

常见问题

问题：“找不到票”

确保股票代码正确
检查您是否使用了正确的市场（美国vs BR vs英国等）
雅虎财经可能无法提供某些股票代码

问题：“缓存权限被拒绝”

确保 ~/.mcp-yfinance/ 目录可写
检查磁盘空间

问题：“找不到模块”

重新安装软件包： pip install --force-reinstall mcp-yfinance
检查Python版本（要求≥3.10）

问题：“SSL证书验证失败”

集 verify=False 服务中初始化（不建议用于生产）
更新CA证书： pip install --upgrade certifi

🤝 贡献

欢迎投稿！请遵循以下指南：

分叉存储库
创建要素分支 (git checkout -b feature/amazing-feature)
编写测试 对于新功能
确保所有测试通过 (pytest)
运行类型检查 (mypy src/mcp_yfinance)
格式代码 (ruff format)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

代码规范

所有代码均为英文（注释、文档字符串、变量名）
所有函数的完整类型提示
谷歌风格的文档字符串
测试覆盖率≥80%
通过mypy严格模式

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

y融资 -雅虎财经API包装器
主控程序 -模型上下文协议
派丹蒂克 -数据验证
Anthropic -克劳德·艾

📞 支持

问题： GitHub问题
讨论： GitHub讨论
电子邮件： your.email@example.com

🗺️ 路线图

v0.2.0（计划中）

[]具有指数回退的高级重试逻辑
[]速率限制保护
[]WebSocket支持实时报价
[]其他市场（中国、韩国、台湾等）

v0.3.0（未来）

[]多个数据源（Alpha Vantage、IEX Cloud）
[]回测工具
[]技术指标（RSI、MACD、布林带）
[]投资组合跟踪

📊 演出

基准测试 （平均硬件）：

操作	无缓存	有缓存	改进
获取股票价格	450ms	15ms	速度提高96%
获取历史数据	1200ms	20ms	速度提高98%
获取选项链	800ms	18ms	速度提高97%
获取财务报表	950毫秒	25毫秒	速度提高97%

缓存命中率： 使用1小时后约85%

由以下材料制成❤️ 对于MCP社区

使用说明

MCP雅虎金融服务器

🌟 特性

🚀 快速开始

通过uvx安装（推荐）

手动安装

🛠️ 配置

市场选择

缓存配置

📚 可用工具

定价和历史数据（6个工具）

1. get_current_stock_price

2. get_stock_price_by_date

3. get_stock_price_date_range

4. get_historical_stock_prices

5. get_dividends

6. get_stock_actions

公司信息（1个工具）

7. get_stock_info

财务报表（3个工具）

8. get_income_statement

9. get_balance_sheet

10. get_cashflow

持有人和所有权（1个工具）

11. get_holder_info

选项（2个工具）

12. get_option_expiration_dates

13. get_option_chain

新闻与分析（5个工具）

14. get_news

15. get_recommendations

16. get_earning_dates

17. get_stock_splits

18. get_analyst_price_targets

💡 使用示例

使用克劳德桌面

巴西市场示例

🏗️ 建筑

项目结构

🧪 发展

设置开发环境

运行测试

类型检查

测试服务器

🔧 故障排除

常见问题

🤝 贡献

代码规范

📄 许可证

🙏 致谢

📞 支持

🗺️ 路线图

v0.2.0（计划中）

v0.3.0（未来）

📊 演出

相关 MCP

AKShare One MCP 股市数据服务

金融数据MCP服务器

加密货币交易集成服务

金融数据服务

金融数据分析服务器

金融数据服务

1. `get_current_stock_price`

2. `get_stock_price_by_date`

3. `get_stock_price_date_range`

4. `get_historical_stock_prices`

5. `get_dividends`

6. `get_stock_actions`

7. `get_stock_info`

8. `get_income_statement`

9. `get_balance_sheet`

10. `get_cashflow`

11. `get_holder_info`

12. `get_option_expiration_dates`

13. `get_option_chain`

14. `get_news`

15. `get_recommendations`

16. `get_earning_dates`

17. `get_stock_splits`

18. `get_analyst_price_targets`