mcp-yfinance
Advanced tools
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.
uvx with no setup requiredAdd to your Claude Desktop configuration (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 .
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 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 |
get_current_stock_priceGet 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"
}
get_stock_price_by_dateGet closing price for a specific date.
Input:
{
"symbol": "MSFT",
"date": "2025-01-10"
}
get_stock_price_date_rangeGet price series for a date range.
Input:
{
"symbol": "GOOGL",
"start_date": "2025-01-01",
"end_date": "2025-01-15"
}
get_historical_stock_pricesGet 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
get_dividendsGet complete dividend payment history.
get_stock_actionsGet all stock actions (dividends + splits).
get_stock_infoGet comprehensive company information (~100 fields).
Output includes:
get_income_statementGet income statement (DRE - Demonstração de Resultados do Exercício).
Input:
{
"symbol": "AAPL",
"freq": "yearly"
}
Frequencies: yearly, quarterly, trailing
get_balance_sheetGet balance sheet (Balanço Patrimonial).
get_cashflowGet cash flow statement.
get_holder_infoGet holder information with 6 different types.
Input:
{
"symbol": "NVDA",
"holder_type": "institutional_holders"
}
Holder types:
major_holders - Major ownership percentagesinstitutional_holders - Institutional investorsmutualfund_holders - Mutual fund holdingsinsider_transactions - Recent insider tradesinsider_purchases - Insider buy transactionsinsider_roster_holders - Current insider rosterget_option_expiration_datesGet all available option expiration dates.
Output:
["2025-01-17", "2025-01-24", "2025-02-21", ...]
get_option_chainGet option chain for specific expiration date.
Input:
{
"symbol": "SPY",
"expiration_date": "2025-01-17",
"option_type": "both"
}
Option types: calls, puts, both
Output includes:
get_newsGet recent news articles.
Output:
[
{
"title": "Apple announces new iPhone",
"summary": "...",
"url": "https://...",
"provider": "Reuters",
"publishedAt": "2025-01-15T10:30:00Z"
}
]
get_recommendationsGet analyst recommendations and upgrades/downgrades.
Input:
{
"symbol": "TSLA",
"recommendation_type": "upgrades_downgrades",
"months_back": 12
}
Recommendation types: recommendations, upgrades_downgrades
get_earning_datesGet earnings announcement dates (past and future).
Input:
{
"symbol": "META",
"limit": 12
}
get_stock_splitsGet historical stock split data.
Input:
{
"symbol": "AAPL"
}
Output:
[
{
"date": "2020-08-31",
"ratio": 4.0
},
{
"date": "2014-06-09",
"ratio": 7.0
}
]
get_analyst_price_targetsGet analyst price targets and estimates.
Input:
{
"symbol": "NVDA"
}
Output includes:
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
Issue: "Ticker not found"
Issue: "Cache permission denied"
~/.mcp-yfinance/ directory is writableIssue: "Module not found"
pip install --force-reinstall mcp-yfinanceIssue: "SSL certificate verification failed"
verify=False in service initialization (not recommended for production)pip install --upgrade certifiContributions are welcome! Please follow these guidelines:
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)This project is licensed under the MIT License - see the LICENSE file for details.
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
FAQs
MCP server providing comprehensive Yahoo Finance data access for AI assistants
We found that mcp-yfinance demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A mini Shai-Hulud campaign compromised Red Hat Cloud Services npm packages to steal developer and CI/CD secrets during installation.
Research
/Security News
The North Korean malware loader hides in a Packagist-listed package and its GitHub branch to fetch and execute remote code in a likely Contagious Interview-style lure.
Security News
The Rust project is moving toward formal rules on LLM use in contributions after months of internal debate over maintainer burden, code quality, and contributor experience.