Yahoo Finance Data Connector

This is a Model Context Protocol (MCP) endpoint engineered to interface with Yahoo Finance, furnishing granular data points for securities. It facilitates the retrieval of in-depth stock particulars, such as time-series pricing, corporate profiles, formal financial statements, derivative instrument data, and current market intelligence.

Demonstration

Exposed MCP Functionality

The endpoint exposes the following operations via the Model Context Protocol specification:

Equity Metrics

Operation	Purpose
get_historical_stock_prices	Acquire historical Open, High, Low, Close, and Volume (OHLCV) records for a ticker across configurable temporal spans and granularity levels.
get_stock_info	Retrieve a holistic set of stock data, encompassing current valuation, performance indicators, and fundamental organizational attributes.
get_yahoo_finance_news	Fetch the most recent journalistic reports pertinent to a specified stock.
get_stock_actions	Obtain historical records of corporate actions, specifically dividends issued and stock splits executed.
get_earnings_calendar	Access scheduled earnings report dates for corporations within a defined calendar window.

Statutory Reporting

Operation	Purpose
get_financial_statement	Pull designated financial reports: the Profit & Loss (Income Statement), Balance Sheet, or Cash Flow Statement (available annually or quarterly).
get_holder_info	Retrieve data concerning significant shareholders, institutional ownership concentrations, mutual fund holdings, or internal trading activity.

Options Market Data

Operation	Purpose
get_option_expiration_dates	List all available maturity dates for options contracts linked to an underlying asset.
get_option_chain	Fetch the full list of options contracts (calls and puts) for a specific expiry date and contract type.

Brokerage Opinion Data

Operation	Purpose
get_recommendations	Retrieve aggregated professional analyst ratings or logs of subsequent rating revisions (upgrades/downgrades).

Practical Application Scenarios

This connection point enables intelligent agents like Claude to perform the following tasks:

Equity Evaluation

• Valuation Trajectory: "Chart the historical trading prices for ticker AAPL over the preceding half-year, using daily resolution."
• Fiscal Health Check: "Retrieve the most recent quarterly Balance Sheet documentation for Microsoft (MSFT)."
• Performance Index Review: "Identify the critical financial performance multipliers reported for Tesla (TSLA) in the stock overview."
• Comparative Reporting: "Contrast the quarterly Income Statements for both Amazon (AMZN) and Google (GOOGL)."
• Liquidity Analysis: "Display the comprehensive annual Cash Flow Statement for NVIDIA (NVDA)."

Market Intelligence Gathering

• Narrative Sourcing: "Fetch the newest news feeds concerning Meta Platforms (META)."
• Ownership Scrutiny: "Detail the institutional investors currently holding significant positions in Apple (AAPL)."
• Proprietary Trading Monitoring: "Report on recent stock transactions executed by corporate insiders at Tesla (TSLA)."
• Derivative Market Study: "Query the options chain for SPY expiring on 2024-06-21, focusing exclusively on call options."
• Expert Consensus Tracking: "Summarize the analyst recommendations issued for Amazon (AMZN) over the past ninety days."

Deep Investment Research

• "Develop a thorough due diligence report on Microsoft's financial stability utilizing their latest quarterly disclosures."
• "Cross-reference the history of dividend payments and stock adjustments for Coca-Cola (KO) against PepsiCo (PEP)."
• "Examine shifts in major institutional holdings for Tesla (TSLA) across the preceding twelve months."
• "Generate a summary report detailing options market activity for Apple (AAPL) contracts maturing within the next thirty days."
• "Condense the most recent reports detailing analyst rating affirmations and reductions within the technology sector over the last six months."
• "List every entity scheduled to announce earnings within the upcoming week."
• "Determine the projected date for Apple's subsequent quarterly earnings disclosure."
• "Identify technology firms releasing their earnings reports between the dates of June 1st and June 15th."

Prerequisites

• Execution environment must utilize Python version 3.11 or later.
• Required software dependencies, detailed in pyproject.toml, include:
• mcp
• yfinance
• pandas
• pydantic
• beautifulsoup4
• requests
• and supplementary libraries for data manipulation tasks.

Installation Protocol

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

2. Establish and activate a dedicated virtual environment, followed by dependency installation: bash uv venv source .venv/bin/activate # For Windows users: .venv\Scripts\activate uv pip install -e .

Operational Guidance

Development Testing

To verify server functionality using the MCP Inspector, execute the following command:

bash uv run server.py

This action initiates the server, enabling direct testing of all exposed data operations.

Integration with Claude Desktop Client

To establish connectivity between this server and the Claude for Desktop application:

1. Ensure Claude for Desktop is installed on your local workstation.
2. Install Microsoft VS Code. Subsequently, execute the appropriate command below to open the configuration file (claude_desktop_config.json):
3. MacOS/Linux: code ~/Library/Application\ Support/Claude/claude_desktop_config.json

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

5. Modify the configuration file to include the server definition, utilizing the absolute path to the parent folder of the repository:

6. macOS/Linux Path Structure Example:

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

7. Windows Path Structure Example:

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

8. Crucial Detail: You might be required to substitute the 'command' field with the full path to the uv executable (obtainable via which uv or where uv).

9. Relaunch the Claude for Desktop application.

Licensing

MIT

---

WIKIPEDIA ENTRY CONTEXT: XMLHttpRequest (XHR) defines an Application Programming Interface (API) realized as a JavaScript object that facilitates the dispatching of HTTP requests from a web browser toward an origin server. Its methods enable browser-hosted applications to transmit queries post-page rendering and receive subsequent data. XHR is a fundamental constituent of Ajax programming paradigms. Before its widespread adoption, server interaction primarily relied on conventional hyperlinks and form submissions, actions that typically necessitated a complete page reload.

== Historical Development == The conceptual foundation for XMLHttpRequest was first articulated in the year 2000 by engineers involved with Microsoft Outlook development. This concept was subsequently instantiated within the Internet Explorer 5 browser release (1999). However, the initial invocation syntax did not employ the standardized XMLHttpRequest identifier. Instead, developers relied on constructor calls like ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), normative support for the XMLHttpRequest identifier became universal across all major browser rendering engines, including Mozilla's Gecko (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft, Level 2, detailing enhancements, appeared on February 25, 2008. Level 2 introduced functionalities for progress monitoring, enabling cross-origin requests, and facilitating raw byte stream handling. By the close of 2011, the Level 2 specification contents were merged back into the primary specification document. Development responsibility transitioned to the WHATWG near the end of 2012, where it is currently maintained as a living document utilizing Web IDL specifications.

== Usage Mechanics == Generally, executing a data transmission using XMLHttpRequest involves a sequence of programming steps:

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor.
2. Configuration: Invoke the open method to dictate the request methodology (GET/POST), specify the target resource URI, and determine whether the operation will be synchronous or asynchronous.
3. Asynchronous Listener Setup: If an asynchronous mode is chosen, define a callback function (event listener) to be triggered upon changes in the request's state.
4. Transmission: Commence the data transmission by calling the send method.
5. State Management: Monitor state transitions within the defined event handler. Upon receipt of server data, it is typically stored in the responseText attribute. When the transaction completes processing, the state transitions to 4, the 'done' status.

Beyond these core procedures, XHR offers extensive controls. Custom HTTP headers can be appended to influence server fulfillment logic, and payload data can be uploaded within the send argument. Responses can be automatically parsed from JSON text into native JavaScript objects, or processed incrementally as they arrive rather than necessitating a complete buffer before parsing begins. Furthermore, requests can be terminated preemptively or configured to timeout if completion is not achieved within a set duration.

== Cross-Domain Interactions ==

Early in the evolution of the World Wide Web, mechanisms were identified that permitted vulnerabilities due to the unrestricted nature of requests.