Finviz + SEC EDGAR MCP Server

get_financial_history

Retrieve actual historical financial metrics from SEC XBRL filings. Get reported values for revenue, net income, EPS, and more for annual or quarterly periods to support financial modeling.

Instructions

Get historical financial data from SEC XBRL filings. Returns actual reported values — not estimates or scraped data.

Args: ticker: Stock ticker symbol. metric: XBRL concept name. Common value-investing metrics: "Revenues" — Total revenue "NetIncomeLoss" — Net income "GrossProfit" — Gross profit "OperatingIncomeLoss" — Operating income "EarningsPerShareBasic" — Basic EPS (use unit "USD/shares") "EarningsPerShareDiluted" — Diluted EPS (use unit "USD/shares") "Assets" — Total assets "Liabilities" — Total liabilities "StockholdersEquity" — Shareholder equity "CashAndCashEquivalentsAtCarryingValue" — Cash on hand "LongTermDebt" — Long-term debt "CommonStockSharesOutstanding" — Shares outstanding (unit "shares") "ResearchAndDevelopmentExpense" — R&D expense "SellingGeneralAndAdministrativeExpense" — SG&A expense "InterestExpense" — Interest expense "IncomeTaxExpenseBenefit" — Income tax expense "DepreciationDepletionAndAmortization" — D&A "CapitalExpenditure" — Capital expenditures "NetCashProvidedByUsedInOperatingActivities" — Operating cash flow "Goodwill" — Goodwill (balance sheet) "IntangibleAssetsNetExcludingGoodwill" — Intangible assets net of goodwill "WeightedAverageNumberOfDilutedSharesOutstanding" — Diluted shares (unit "shares") periods: Number of recent periods to show (default 8). period_type: Controls which filings are included: "annual" — Annual filings (10-K / 20-F / 40-F). Clean year-over-year series. RECOMMENDED for financial modeling. "quarterly" — 10-Q only. Clean quarter-over-quarter series, useful for recent trend analysis. "interim" — Interim filings (10-Q / 6-K). Includes foreign private issuer interim XBRL when present. May include both ~3-month and ~6-month periods. "all" — Annual + interim filings mixed (not recommended for modeling).

Input Schema

TableJSON Schema

Name	Required	Default
`metric`	No	Revenues
`ticker`	Yes
`periods`	No
`period_type`	No	annual

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.2.0Sep 25, 2026

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that values are 'actual reported values — not estimates or scraped data' and highlights quirks like interim filings possibly including both 3-month and 6-month periods. It also notes that 'all' mixes filing types. These are valuable behavioral insights, though it doesn't cover rate limits, errors, or pagination, which are minor for this data retrieval tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured: a brief intro, then an Args section with bullet points. It is front-loaded with the core purpose and then provides necessary parameter details. Every metric line earns its place, though the metric list could potentially be condensed by referencing a full taxonomy. It is not excessively verbose given the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values are covered by that. The description thoroughly documents all four parameters and their nuances, including period_type behavior. It lacks details on edge cases like invalid tickers or error handling, but for a historical data retrieval tool with an output schema, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully compensate. It does: it explains ticker, lists over 20 common XBRL metrics with human-readable meanings, defines periods with a default, and details four period_type options with their filing sources and use cases. This exceeds what the bare schema provides and is essential for correct usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get historical financial data from SEC XBRL filings.' It specifies the resource (SEC XBRL) and distinguishes it from estimates or scraped data, setting it apart from sibling tools like get_financial_ttm or get_financial_snapshot. The verb 'get' and the resource are explicit and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use different period_type values, with 'annual' recommended for financial modeling and 'quarterly' for recent trend analysis. It also warns that 'all' is not recommended for modeling. However, it does not explicitly name alternative tools or state when to avoid this tool entirely, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.