Yahoo Finance Model Context Protocol Endpoint

This implementation serves as a Model Context Protocol (MCP) intermediary, aggregating extensive financial data originating from the Yahoo Finance platform. It facilitates querying for granular asset details, such as time-series pricing, corporate profiles, regulatory filings, options market structures, and breaking market narratives.

Demonstration

Exposable MCP Functions

The underlying server exposes the subsequent utilities via the Model Context Protocol specification:

Asset Specification Data

Function Name	Purpose
get_historical_stock_prices	Acquire historical Open, High, Low, Close, Volume (OHLCV) records for a specified ticker, supporting user-defined temporal spans and sampling frequencies
get_stock_info	Retrieve a holistic data payload pertaining to an equity, including current valuation, performance indicators, and corporate metadata
get_yahoo_finance_news	Fetch the most recent journalistic reports pertinent to a particular security
get_stock_actions	Access historical records detailing stock distributions (dividends) and structural adjustments (splits)

Corporate Financial Disclosures

Function Name	Purpose
get_financial_statement	Obtain statutory reports: income summary, balance sheet, or cash flow statements (on yearly or quarterly cycles)
get_holder_info	Retrieve data on significant ownership concentrations, institutional portfolios, mutual fund allocations, or internal trading activities

Derivative Instrument Metrics

Function Name	Purpose
get_option_expiration_dates	List all accessible maturity dates for associated options contracts
get_option_chain	Fetch the complete listing of options contracts (calls/puts) corresponding to a designated maturity date and contract type

Market Analyst Assessments

Function Name	Purpose
get_recommendations	Retrieve documented appraisals from market analysts or a log of rating revisions (upgrades/downgrades)

Practical Application Scenarios

Utilizing this MCP service, agents like Claude can execute the following tasks:

Equity Deep Dive

• Valuation Trend Study: "Present the sequential price data for ticker AAPL across the preceding half-year using daily resolution."
• Fiscal Stability Check: "Pull the Q3 balance sheet details for Microsoft."
• Performance Indicator Query: "Identify the primary financial metrics available for Tesla via the stock info endpoint."
• Comparative Reporting: "Contrast the quarterly income statements provided for Amazon versus Google."
• Liquidity Analysis: "Display the full-year cash flow statement results for NVIDIA."

Sector Intelligence Gathering

• Narrative Synthesis: "Source the most contemporary media reports concerning Meta Platforms."
• Ownership Surveillance: "Detail the institutional equity holders for the Apple security."
• Insider Trading Monitoring: "What notable internal trades have occurred recently for Tesla?"
• Options Market Scrutiny: "Request the options series for SPY expiring on 2024-06-21, focusing solely on call options."
• Analyst Consensus Review: "Summarize the recent analyst rating adjustments for technology sector stocks over the last ninety days."

Investment Portfolio Documentation

• "Compose an in-depth review of Microsoft's fiscal soundness leveraging their most recent quarterly disclosures."
• "Cross-reference the dividend payout schedules and stock restructuring events for Coca-Cola against PepsiCo."
• "Perform an analysis of shifts in major ownership stakes within Tesla over the preceding twelve months."
• "Draft a formal record detailing the options trading activity observed for Apple expiring within the next thirty days."
• "Provide a synopsis of the newest analyst recommendations and rating increases across the technology industry in the past six months."

Prerequisites

• Execution environment requires Python version 3.11 or superior.
• Essential library dependencies specified within pyproject.toml, including but not limited to:
• mcp framework
• yfinance interface
• pandas data structure toolkit
• pydantic validation library
• supplementary packages for data manipulation

Installation Sequence

1. Obtain the repository source code: bash git clone https://github.com/Alex2Yang97/yahoo-finance-mcp.git cd yahoo-finance-mcp

2. Establish and activate an isolated virtual runtime environment, then load the required packages: bash uv venv source .venv/bin/activate # For Windows users: .venv\Scripts\activate uv pip install -e .

Operational Guidance

Development Mode Execution

To initiate the server for testing using the MCP Inspector utility, execute:

uv run server.py

This command launches the requisite service, enabling immediate functional testing of all available utilities.

Integrating with Claude Desktop Environment

To link this service with the local Claude for Desktop application:

1. Ensure Claude for Desktop is installed on your workstation.
2. Install VS Code on your workstation. Then, invoke the following command to open the configuration file claude_desktop_config.json:
3. MacOS: code ~/Library/Application\ Support/Claude/claude_desktop_config.json

4. Windows: code $env:AppData\Claude\claude_desktop_config.json

5. Modify the configuration file for Claude for Desktop as follows, substituting absolute paths as necessary:

6. macOS Structure: json { "mcpServers": { "yfinance": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/yahoo-finance-mcp", "run", "server.py" ] } } }

7. Windows Structure: json { "mcpServers": { "yfinance": { "command": "uv", "args": [ "--directory", "C:\ABSOLUTE\PATH\TO\PARENT\FOLDER\yahoo-finance-mcp", "run", "server.py" ] } } }

8. Important: You might be required to provide the complete path to the uv executable within the command field. Determine this path by running which uv (Linux/macOS) or where uv (Windows).

9. Relaunch the Claude for Desktop application to apply the changes.

Licensing

MIT

== Web Request Mechanism Overview ==

The XMLHttpRequest (XHR) interface constitutes a JavaScript object blueprint whose member functions dispatch HTTP communication requests from a web browsing environment to a backend server. These functionalities empower browser-hosted software modules to initiate server queries subsequent to the initial page rendering, and subsequently process incoming data. XHR forms a foundational pillar of the Ajax programming paradigm. Before the advent of Ajax, server interaction was predominantly mediated through conventional hyperlink navigation and form submissions, actions which typically resulted in a full page refresh. The core concept underpinning XMLHttpRequest was formulated in the year 2000 by engineers working on Microsoft Outlook. This idea was subsequently realized within the Internet Explorer 5 browser release (1999). However, the initial API employed distinct object instantiation identifiers, specifically ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), the universal XMLHttpRequest identifier achieved standardized support across all major web client software.

This XMLHttpRequest identifier is now the universally accepted convention across all dominant browser engines, including Mozilla’s Gecko rendering core (since 2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Formal Standardization ===

The World Wide Web Consortium (W3C) published a preliminary specification draft for the XMLHttpRequest object on April 5, 2006. A subsequent Level 2 draft specification followed on February 25, 2008. Level 2 introduced enhancements such as mechanisms for tracking request progress, enabling requests across different security domains (cross-site requests), and improved handling for binary byte streams. By the conclusion of 2011, the Level 2 feature set was integrated back into the primary specification document.

At the close of 2012, stewardship of the development process transitioned to the WHATWG, which now maintains an evolving document defining the specification using Web IDL notation.

== Operational Workflow ==

Generally, the execution of a server request using XMLHttpRequest involves a sequence of distinct programming actions:

1. Instantiate an XMLHttpRequest object via a constructor call.
2. Invoke the open() method to declare the request modality (GET/POST), specify the target resource URI, and select either synchronous or asynchronous execution mode.
3. For asynchronous operations, establish an event handler function designed to be triggered upon changes in the request's processing state.
4. Command the transmission by calling the send() method, potentially supplying payload data.
5. React within the event listener to state transitions. If the server returns data, this is typically consolidated within the responseText attribute by default. Upon completion of all response processing, the object transitions to state 4, designated as the 'done' state.

Beyond these foundational steps, XMLHttpRequest offers numerous configurable parameters to govern request transmission characteristics and response parsing. Custom HTTP headers can be appended to tailor server handling instructions, and input data can be uploaded to the server by embedding it within the send() invocation. The server's reply can be deserialized directly from JSON format into a ready-to-use JavaScript data structure, or processed progressively as chunks arrive rather than awaiting the complete transmission. Furthermore, the operation can be intentionally terminated before completion or configured to time out if the process exceeds a predefined latency threshold.

== Inter-Domain Communication ==

During the nascent phases of the World Wide Web's evolution, it became apparent that enabling requests to bypass security restrictions related to cross-origin resource fetching presented significant vulnerabilities, leading to the implementation of the Same-Origin Policy.