mcp-yfinance 0.1.0

MCP server providing comprehensive Yahoo Finance data access for AI assistants

MCP Yahoo Finance Server

A production-ready Model Context Protocol (MCP) server providing comprehensive access to Yahoo Finance data through 18 specialized tools. Features intelligent caching, multi-market support, and complete type safety.

🌟 Features

• 18 Comprehensive Tools - Complete coverage of pricing, financials, options, holders, and news
• Intelligent SQLite Caching - Reduces latency by 90% with TTL-based cache management
• Multi-Market Support - Works globally with configurable market normalization (US, BR, UK, DE, FR, JP, IN, HK, AU, CA, and more)
• Type-Safe - Full Pydantic models with complete type hints throughout
• Production-Ready - Robust error handling with custom exception hierarchy
• Zero Configuration - Deploy instantly via uvx with no setup required
• Async/Await - Optimized for concurrent operations

🚀 Quick Start

Installation via uvx (Recommended)

Add to your Claude Desktop configuration (claude_desktop_config.json):

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

Manual Installation

# 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 .

🛠️ Configuration

Market Selection

Set your default market via environment variable:

# 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

Supported Markets:

• US - United States (no suffix)
• BR - Brazil (.SA)
• UK - United Kingdom (.L)
• DE - Germany (.DE)
• FR - France (.PA)
• JP - Japan (.T)
• IN_NSE - India NSE (.NS)
• IN_BSE - India BSE (.BO)
• HK - Hong Kong (.HK)
• AU - Australia (.AX)
• CA - Canada (.TO)

Cache Configuration

Cache is automatically created at ~/.mcp-yfinance/cache.db with the following TTLs:

Data Type	TTL	Use Case
Current Quotes	5 min	Real-time price tracking
Option Chains	5 min	Options trading
News	30 min	Recent news updates
Stock Info	1 hour	Company information
Historical Data	24 hours	Price history
Financial Statements	24 hours	Quarterly/annual reports
Holders	24 hours	Ownership data
Recommendations	24 hours	Analyst ratings

📚 Available Tools

Pricing & Historical Data (6 tools)

1. get_current_stock_price

Get current stock price with day change information.

Input:

{
  "symbol": "AAPL"
}

Output:

{
  "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

Get closing price for a specific date.

Input:

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

3. get_stock_price_date_range

Get price series for a date range.

Input:

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

4. get_historical_stock_prices

Get full OHLCV (Open, High, Low, Close, Volume) historical data.

Input:

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

Supported periods: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max

Supported intervals: 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo

5. get_dividends

Get complete dividend payment history.

6. get_stock_actions

Get all stock actions (dividends + splits).

---

Company Information (1 tool)

7. get_stock_info

Get comprehensive company information (~100 fields).

Output includes:

• Company name, sector, industry
• Market cap, enterprise value
• P/E ratio, dividend yield
• 52-week high/low
• Beta, trailing EPS
• And much more...

---

Financial Statements (3 tools)

8. get_income_statement

Get income statement (DRE - Demonstração de Resultados do Exercício).

Input:

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

Frequencies: yearly, quarterly, trailing

9. get_balance_sheet

Get balance sheet (Balanço Patrimonial).

10. get_cashflow

Get cash flow statement.

---

Holders & Ownership (1 tool)

11. get_holder_info

Get holder information with 6 different types.

Input:

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

Holder types:

• major_holders - Major ownership percentages
• institutional_holders - Institutional investors
• mutualfund_holders - Mutual fund holdings
• insider_transactions - Recent insider trades
• insider_purchases - Insider buy transactions
• insider_roster_holders - Current insider roster

---

Options (2 tools)

12. get_option_expiration_dates

Get all available option expiration dates.

Output:

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

13. get_option_chain

Get option chain for specific expiration date.

Input:

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

Option types: calls, puts, both

Output includes:

• Contract symbols
• Strike prices
• Last prices, bid, ask
• Volume and open interest
• Implied volatility

---

News & Analysis (5 tools)

14. get_news

Get recent news articles.

Output:

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

15. get_recommendations

Get analyst recommendations and upgrades/downgrades.

Input:

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

Recommendation types: recommendations, upgrades_downgrades

16. get_earning_dates

Get earnings announcement dates (past and future).

Input:

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

17. get_stock_splits

Get historical stock split data.

Input:

{
  "symbol": "AAPL"
}

Output:

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

18. get_analyst_price_targets

Get analyst price targets and estimates.

Input:

{
  "symbol": "NVDA"
}

Output includes:

• Current price
• Target mean, median, high, low
• Number of analysts
• Recommendation (buy/hold/sell)

---

💡 Usage Examples

With Claude Desktop

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...

Brazilian Market Example

{
  "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...

---

🏗️ Architecture

┌──────────────────────────────────┐
│   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)            │
└──────────────────────────────────┘

Project Structure

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

---

🧪 Development

Setup Development Environment

# 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]"

Running Tests

# Run all tests
pytest

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

# Run specific test file
pytest tests/test_service.py

Type Checking

# Run mypy
mypy src/mcp_yfinance

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

Testing the Server

# 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

---

🔧 Troubleshooting

Common Issues

Issue: "Ticker not found"

• Make sure the ticker symbol is correct
• Check if you're using the right market (US vs BR vs UK, etc.)
• Some tickers may not be available on Yahoo Finance

Issue: "Cache permission denied"

• Ensure ~/.mcp-yfinance/ directory is writable
• Check disk space

Issue: "Module not found"

• Reinstall package: pip install --force-reinstall mcp-yfinance
• Check Python version (requires ≥3.10)

Issue: "SSL certificate verification failed"

• Set verify=False in service initialization (not recommended for production)
• Update CA certificates: pip install --upgrade certifi

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for new functionality
4. Ensure all tests pass (pytest)
5. Run type checking (mypy src/mcp_yfinance)
6. Format code (ruff format)
7. Commit changes (git commit -m 'Add amazing feature')
8. Push to branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Code Standards

• All code in English (comments, docstrings, variable names)
• Complete type hints on all functions
• Google-style docstrings
• Test coverage ≥80%
• Pass mypy strict mode

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• yfinance - Yahoo Finance API wrapper
• MCP - Model Context Protocol
• Pydantic - Data validation
• Anthropic - Claude AI

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

🗺️ Roadmap

v0.2.0 (Planned)

• Advanced retry logic with exponential backoff
• Rate limiting protection
• WebSocket support for real-time quotes
• Additional markets (CN, KR, TW, etc.)

v0.3.0 (Future)

• Multiple data sources (Alpha Vantage, IEX Cloud)
• Backtesting tools
• Technical indicators (RSI, MACD, Bollinger Bands)
• Portfolio tracking

---

📊 Performance

Benchmarks (on average hardware):

Operation	Without Cache	With Cache	Improvement
Get Stock Price	450ms	15ms	96% faster
Get Historical Data	1200ms	20ms	98% faster
Get Option Chain	800ms	18ms	97% faster
Get Financial Statements	950ms	25ms	97% faster

Cache hit rate: ~85% after 1 hour of usage

---

Made with ❤️ for the MCP community