> ## Documentation Index
> Fetch the complete documentation index at: https://finance.chiefpriest.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Sources

> Understanding YFinance and FMP data sources for optimal financial analysis

## Overview

The Financial MCP Server integrates two complementary data sources to provide comprehensive financial information. Each source has distinct advantages and use cases.

<CardGroup cols={2}>
  <Card title="YFinance" icon="python" color="#3776AB">
    **Free Python Library**

    * Yahoo Finance data scraping
    * No API key required
    * Subject to rate limiting
    * 6 tools available
  </Card>

  <Card title="Financial Modeling Prep" icon="chart-line" color="#0D9373">
    **Professional API Service**

    * Reliable, structured data
    * API key required
    * 250+ requests/day free tier
    * 26 professional tools
  </Card>
</CardGroup>

## YFinance Data Source

### What is YFinance?

YFinance is a Python library that scrapes financial data directly from Yahoo Finance. It's **not an API** but rather a web scraping tool that mimics browser requests to Yahoo's servers.

```python theme={null}
import yfinance as yf

# This is what happens under the hood
ticker = yf.Ticker("AAPL")
info = ticker.info  # Scrapes Yahoo Finance web pages
```

### Advantages

<AccordionGroup>
  <Accordion title="✅ Completely Free">
    No API keys, subscriptions, or usage fees required
  </Accordion>

  <Accordion title="✅ No Registration">
    Works immediately without any setup or account creation
  </Accordion>

  <Accordion title="✅ Rich Historical Data">
    Access to years of historical price and volume data
  </Accordion>

  <Accordion title="✅ Popular & Well-Maintained">
    Large community, frequent updates, extensive documentation
  </Accordion>
</AccordionGroup>

### Limitations

<AccordionGroup>
  <Accordion title="⚠️ Rate Limiting">
    Yahoo Finance may temporarily block requests if too many are made
  </Accordion>

  <Accordion title="⚠️ Reliability Issues">
    Web scraping can break if Yahoo changes their website structure
  </Accordion>

  <Accordion title="⚠️ No Official Support">
    Yahoo doesn't officially support programmatic access
  </Accordion>

  <Accordion title="⚠️ Limited Advanced Features">
    Basic financial data only, no professional analytics
  </Accordion>
</AccordionGroup>

### Available YFinance Tools

| Tool                       | Description            | Use Case             |
| -------------------------- | ---------------------- | -------------------- |
| `get_stock_quote`          | Real-time stock prices | Portfolio tracking   |
| `get_company_overview`     | Company information    | Research             |
| `get_time_series_daily`    | Historical data        | Backtesting          |
| `search_symbol`            | Symbol lookup          | Discovery            |
| `get_recommendations`      | Analyst ratings        | Investment decisions |
| `get_insider_transactions` | Insider trading        | Sentiment analysis   |

## Financial Modeling Prep (FMP)

### What is FMP?

Financial Modeling Prep is a professional financial data API service that provides institutional-grade financial information through a structured REST API.

```python theme={null}
# Professional API with structured responses
response = requests.get(
    "https://financialmodelingprep.com/api/v3/quote/AAPL",
    params={"apikey": "your_api_key"}
)
```

### Advantages

<AccordionGroup>
  <Accordion title="✅ Professional Reliability">
    99.9% uptime, structured data, official API support
  </Accordion>

  <Accordion title="✅ Comprehensive Coverage">
    26 professional tools covering all aspects of financial analysis
  </Accordion>

  <Accordion title="✅ Advanced Features">
    DCF valuations, technical indicators, options data, insider trading
  </Accordion>

  <Accordion title="✅ Real-time Data">
    Live market data with minimal latency
  </Accordion>

  <Accordion title="✅ Scalable">
    From 250 requests/day (free) to millions (enterprise)
  </Accordion>
</AccordionGroup>

### Pricing Tiers

| Tier             | Requests/Day | Price      | Best For             |
| ---------------- | ------------ | ---------- | -------------------- |
| **Free**         | 250          | \$0        | Development, testing |
| **Starter**      | 1,000        | \$15/month | Small applications   |
| **Professional** | 10,000       | \$50/month | Production apps      |
| **Enterprise**   | 1,000,000+   | Custom     | Large scale          |

### Available FMP Tools

#### Core Financial Data (4 tools)

* `fmp_get_stock_quote` - Real-time quotes
* `fmp_get_financial_statements` - Income, balance sheet, cash flow
* `fmp_get_key_metrics` - Financial ratios and metrics
* `fmp_get_dcf_valuation` - Discounted cash flow analysis

#### Market Data (4 tools)

* `fmp_get_market_gainers` - Top gaining stocks
* `fmp_get_market_losers` - Biggest losers
* `fmp_get_most_active` - Highest volume stocks
* `fmp_get_sector_performance` - Sector analysis

#### Advanced Screening (6 tools)

* `fmp_stock_screener` - Multi-criteria screening
* `fmp_search_advanced` - Enhanced search
* `fmp_get_stock_news` - Financial news
* `fmp_get_price_targets` - Analyst targets
* `fmp_get_upgrades_downgrades` - Rating changes
* `fmp_get_insider_trading_latest` - Insider activity

#### Options & Technical (4 tools)

* `fmp_get_options_chain` - Options data
* `fmp_get_options_volume` - Options activity
* `fmp_get_technical_indicators` - RSI, MACD, etc.
* `fmp_get_moving_averages` - Technical analysis

#### International & Alternative (4 tools)

* `fmp_get_international_gainers` - Global markets
* `fmp_get_currency_rates` - Forex data
* `fmp_get_crypto_prices` - Cryptocurrency
* `fmp_get_commodities` - Commodity prices

#### Professional Analytics (4 tools)

* `fmp_get_analyst_estimates` - Earnings estimates
* `fmp_get_earnings_surprises` - Beat/miss data
* `fmp_get_senate_trades` - Government trading
* `fmp_get_house_trades` - Congressional activity

## Comparison Matrix

| Feature                   | YFinance           | FMP              |
| ------------------------- | ------------------ | ---------------- |
| **Cost**                  | Free               | Free tier + paid |
| **Reliability**           | Moderate           | High             |
| **Setup**                 | None               | API key required |
| **Rate Limits**           | Yahoo's discretion | Clearly defined  |
| **Data Quality**          | Good               | Professional     |
| **Advanced Features**     | Basic              | Extensive        |
| **Support**               | Community          | Official         |
| **Real-time Data**        | Yes                | Yes              |
| **Historical Data**       | Extensive          | Extensive        |
| **International Markets** | Limited            | Comprehensive    |

## Best Practices

### When to Use YFinance

<AccordionGroup>
  <Accordion title="Development & Testing">
    Perfect for prototyping and development without API key setup
  </Accordion>

  <Accordion title="Basic Portfolio Tracking">
    Simple price monitoring and basic company information
  </Accordion>

  <Accordion title="Educational Projects">
    Learning financial programming without cost barriers
  </Accordion>

  <Accordion title="FMP Quota Exceeded">
    Fallback when FMP daily limits are reached
  </Accordion>
</AccordionGroup>

### When to Use FMP

<AccordionGroup>
  <Accordion title="Production Applications">
    Reliable data for user-facing applications
  </Accordion>

  <Accordion title="Professional Analysis">
    Advanced metrics, ratios, and valuation models
  </Accordion>

  <Accordion title="High-Volume Usage">
    Applications requiring many daily requests
  </Accordion>

  <Accordion title="Comprehensive Coverage">
    Need for options, international, or alternative asset data
  </Accordion>
</AccordionGroup>

## Server Implementation

Our server implements an intelligent fallback system:

```mermaid theme={null}
flowchart TD
    A[Request] --> B{Endpoint Type}
    B -->|Basic Data| C[Try YFinance First]
    B -->|Advanced Data| D[Use FMP Directly]
    C -->|Success| E[Return YFinance Data]
    C -->|Rate Limited| F[Fallback to FMP]
    F --> G[Return FMP Data]
    D --> H[Return FMP Data]
```

### Rate Limiting Handling

The server automatically handles rate limiting:

```python theme={null}
# Automatic retry with exponential backoff
def handle_yfinance_request(func, *args, **kwargs):
    max_retries = 3
    for attempt in range(max_retries):
        try:
            return func(*args, **kwargs)
        except RateLimitError:
            wait_time = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait_time)
```

## Getting Started

### 1. No Setup Required (YFinance)

```bash theme={null}
# Works immediately
curl "http://localhost:8001/api/v1/stock/AAPL/yfinance"
```

### 2. FMP Setup (Recommended)

```bash theme={null}
# Get free API key at financialmodelingprep.com
export FMP_API_KEY="your_api_key"
curl "http://localhost:8001/api/v1/stock/AAPL"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Get FMP API Key" icon="key" href="https://financialmodelingprep.com/developer/docs">
    Sign up for free FMP account (250 requests/day)
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore all 32 available financial tools
  </Card>

  <Card title="Installation Guide" icon="download" href="/installation">
    Set up the server with both data sources
  </Card>

  <Card title="MCP Integration" icon="robot" href="/concepts/mcp-protocol">
    Connect with AI agents like Claude
  </Card>
</CardGroup>