Skip to main content

​
Overview

FinMCP provides three related tools for accessing earnings information:
  1. yf_ticker_earnings - Historical earnings data
  2. yf_ticker_calendar - Upcoming calendar events including earnings
  3. yf_ticker_earnings_dates - Detailed earnings date history with controls
Each tool serves different use cases for analyzing company earnings.

​
yf_ticker_earnings

Retrieves historical earnings data for a ticker, showing actual reported earnings over time.

​
Parameters

​
ticker
string
required
Ticker symbol to retrieve earnings for (e.g., “AAPL”, “MSFT”, “GOOGL”)
​
response_format
string
default:"json"
Format for the response:
  • json - Returns structured JSON data
  • markdown - Returns a formatted markdown table
​
preview_limit
number
default:"25"
When using response_format="markdown", limits the number of rows displayed (1-200)
​
save
object
Options to save the result to a file:
  • format - Either “csv” or “json”
  • filename - Optional custom filename (defaults to auto-generated)

​
Data Returned

Historical earnings typically include:
  • Earnings Date - When earnings were reported
  • EPS Estimate - Analyst consensus estimate
  • EPS Actual - Actual reported earnings per share
  • Surprise % - Percentage beat or miss vs. estimates
  • Revenue - Reported revenue figures

​
Example

{
  "ticker": "AAPL",
  "response_format": "markdown"
}

​
yf_ticker_calendar

Retrieves upcoming calendar events for a ticker, including the next earnings date, ex-dividend date, and other important dates.

​
Parameters

​
ticker
string
required
Ticker symbol to retrieve calendar for (e.g., “AAPL”, “MSFT”, “GOOGL”)
​
response_format
string
default:"json"
Format for the response:
  • json - Returns structured JSON data
  • markdown - Returns a formatted markdown table
​
preview_limit
number
default:"25"
When using response_format="markdown", limits the number of rows displayed (1-200)
​
save
object
Options to save the result to a file:
  • format - Either “csv” or “json”
  • filename - Optional custom filename (defaults to auto-generated)

​
Data Returned

Calendar information typically includes:
  • Earnings Date - Next scheduled earnings announcement
  • Earnings Average - Consensus EPS estimate
  • Earnings Low - Low-end EPS estimate
  • Earnings High - High-end EPS estimate
  • Revenue Average - Consensus revenue estimate
  • Revenue Low - Low-end revenue estimate
  • Revenue High - High-end revenue estimate
  • Ex-Dividend Date - Date when stock trades without dividend
  • Dividend Date - Date when dividend is paid

​
Example

{
  "ticker": "MSFT"
}

​
yf_ticker_earnings_dates

Retrieves a comprehensive list of earnings dates for a ticker with advanced filtering and sorting options. This tool provides more control than yf_ticker_earnings for accessing historical earnings dates.

​
Parameters

​
ticker
string
required
Ticker symbol to retrieve earnings dates for (e.g., “AAPL”, “MSFT”, “GOOGL”)
​
limit
number
default:"12"
Maximum number of earnings dates to return (1-400). Controls how many historical/future earnings dates are retrieved.
​
sort
string
Sort order for the earnings dates. Common values:
  • "asc" - Ascending order (oldest first)
  • "desc" - Descending order (newest first)
If not specified, uses the default API ordering.
​
response_format
string
default:"json"
Format for the response:
  • json - Returns structured JSON data
  • markdown - Returns a formatted markdown table
​
preview_limit
number
default:"25"
When using response_format="markdown", limits the number of rows displayed (1-200)
​
save
object
Options to save the result to a file:
  • format - Either “csv” or “json”
  • filename - Optional custom filename (defaults to auto-generated)

​
Data Returned

Detailed earnings dates including:
  • Earnings Date - Date and time of earnings announcement
  • EPS Estimate - Analyst consensus estimate
  • Reported EPS - Actual reported earnings per share
  • Surprise % - Beat or miss percentage

​
Examples

​
Get Last 20 Earnings Dates

{
  "ticker": "GOOGL",
  "limit": 20,
  "sort": "desc"
}

​
Get Earliest 10 Earnings Dates

{
  "ticker": "TSLA",
  "limit": 10,
  "sort": "asc"
}

​
Retrieve Maximum Historical Data

{
  "ticker": "NVDA",
  "limit": 400
}

​
Tool Comparison

​
When to Use Each Tool

ToolBest Used ForKey Features
yf_ticker_earningsQuick earnings summarySimple historical earnings data
yf_ticker_calendarUpcoming eventsNext earnings date and estimates
yf_ticker_earnings_datesDetailed historyAdvanced filtering with limit/sort

​
Example: Complete Earnings Analysis

Combine all three tools for comprehensive earnings analysis: 
// 1. Get upcoming earnings date
{
  "ticker": "AAPL"
}
// Use: yf_ticker_calendar

// 2. Get recent earnings history
{
  "ticker": "AAPL",
  "limit": 8,
  "sort": "desc"
}
// Use: yf_ticker_earnings_dates

// 3. Get full historical earnings data
{
  "ticker": "AAPL",
  "response_format": "markdown"
}
// Use: yf_ticker_earnings

Build docs developers (and LLMs) love

Get started for freeTalk to us