
A Model Context Protocol (MCP) server for Yahoo Finance.
A Model Context Protocol (MCP) server for Yahoo Finance.
·
MCP Yahoo Finance is a Model Context Protocol (MCP) server. It gets data from Yahoo Finance. You can use it to get stock prices, company data, past prices, financial reports, news, analyst ratings, earnings dates, dividends, and options data.
This project is in early development. Tool names and response fields can change between releases.
You can run mcp-yahoo-finance without a separate install. Use uvx.
pip install mcp-yahoo-financeClone the repository. Then install the development environment:
git clone [email protected]:maxscheijen/mcp-yahoo-finance.git
cd mcp-yahoo-finance
uv syncAdd this entry to your claude_desktop_config.json file:
{
"mcpServers": {
"yahoo-finance": {
"command": "uvx",
"args": ["mcp-yahoo-finance"]
}
}
}You can also use Docker. Replace IMAGE with the Docker image name:
{
"mcpServers": {
"yahoo-finance": {
"command": "docker",
"args": ["run", "-i", "--rm", "IMAGE"]
}
}
}Add this entry to your .vscode/mcp.json file:
{
"servers": {
"yahoo-finance": {
"command": "uvx",
"args": ["mcp-yahoo-finance"]
}
}
}You can ask questions like these:
Tools return data in JSON format. This is an example of a rich quote:
{
"symbol": "AAPL",
"currentPrice": 243.5822,
"previousClose": 241.33,
"absoluteChange": 2.2522,
"percentChange": 0.9331,
"open": 242.1,
"dayHigh": 244.2,
"dayLow": 241.9,
"volume": 45678901,
"marketStatus": "REGULAR",
"currency": "USD",
"exchange": "NMS",
"timestamp": "2025-01-02T15:30:00+00:00",
"source": {
"provider": "Yahoo Finance",
"endpoint": "info",
"fetchedAt": "2025-01-02T15:30:01+00:00"
}
}Errors use the same format for all tools. An error includes an error code and a message:
{
"error": {
"code": "NO_DATA",
"message": "No historical data found for AAPL"
}
}Historical and table results keep the column names from the data source. Dates use the YYYY-MM-DD format. The server does not show the time zone used by Yahoo Finance.
Historical price tools return adjusted prices by default. Adjusted prices include changes from stock splits and dividends. To get prices without these changes, set adjusted to false in get_historical_stock_prices.
Date searches include both the start date and the end date. If a date is a weekend or market holiday, there may be no price data for that date. In that case, the tool returns a NO_DATA error.
If quote or company data is missing, its value is null. The news tool returns 10 articles by default. It can return up to 100 articles. It includes the title, URL, publisher, thumbnail, related stock symbols, and publish time. The publish time uses UTC and the ISO 8601 format. You can set start_date and end_date to filter news. The filter includes both dates.
Recommendation, earnings, dividend, financial report, and options tools use a top-level symbol field. They return data from Yahoo Finance when that data is available.
Use Yahoo Finance ticker symbols for symbol values. Examples are AAPL and MSFT.
| Tool | Purpose |
|---|---|
get_current_stock_price | Gets the current stock price and quote data. |
get_rich_quote | Gets a quote with price, price change, trading range, market status, and source data. |
get_company_overview | Gets a company profile with its sector, industry, market value, website, employee count, description, and source data. |
get_symbol_comparison | Compares current quotes for up to 20 symbols. |
get_performance_analysis | Compares returns, moving averages, volatility, drawdown, benchmark returns, and correlation for multiple symbols. |
get_portfolio_analysis | Calculates position values and allocations from quantities, weighted portfolio returns from weights, or per-symbol watchlist metrics without sizing. |
get_stock_price_by_date | Gets the adjusted closing price for one trading date. |
get_stock_price_date_range | Gets adjusted closing prices for a date range. |
get_historical_stock_prices | Gets past prices for a period and time interval. |
get_dividends | Gets past dividend payments. |
get_stock_splits | Gets past stock splits. |
get_capital_gains | Gets capital-gains payments. |
get_upcoming_dividends | Gets future dividend dates and rates. |
get_earnings_analytics | Gets earnings results and estimates. |
get_income_statement | Gets an income statement by year, quarter, or trailing period. |
get_cashflow | Gets a cash flow statement by period. |
get_earning_dates | Gets past and future earnings dates. |
get_news | Gets Yahoo Finance news. You can set date filters. |
get_recommendations | Gets analyst recommendations. |
get_option_expiration_dates | Gets available option expiration dates. |
get_option_chain | Gets calls and puts for one expiration date. You can filter by strike price, moneyness, liquidity, spread, type, and number of results. |
get_option_summary | Gets implied volatility, open interest, volume, put/call ratios, and max pain for one expiration date. |
Performance analysis uses closing prices adjusted for stock splits and dividends.
Total return is (last close / first close) - 1.
Annual volatility is the standard deviation of daily returns multiplied by sqrt(252).
Maximum drawdown is the largest fall from a previous high.
The tool calculates correlation from daily returns on dates shared by the symbols. This lets it compare symbols that have different trading calendars.
get_portfolio_analysis accepts symbols, start_date, and end_date, plus either quantities, weights, or neither. Quantities report current market value and value-based allocations. Weights are normalized and applied to daily adjusted returns. Omitting both quantities and weights selects watchlist mode and returns per-symbol metrics without portfolio totals. Historical performance uses adjusted close prices; current market values use Yahoo's current quote. Portfolio totals require every available position to report the same currency. Missing history or quotes are omitted and described in errors. Unequal trading calendars use forward-filled closes for aggregate daily returns.
Run uv sync to install the locked development environment. Then run these commands:
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv buildYou can also use these Makefile commands:
make test
make lint
make docker-buildThe tests use mock Yahoo Finance data. They do not make live requests to Yahoo Finance.
Run this command:
docker build -t mcp-yahoo-finance .Run this command:
npx @modelcontextprotocol/inspector uv run mcp-yahoo-financeYahoo Finance is a third-party data source. Its data can be late, incomplete, or unavailable. This project does not give investment advice. It does not guarantee that the data is correct, complete, or up to date. Check important data with an authoritative source before you use it.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add yahoo-finance -- uvx mcp-yahoo-finance{
"mcpServers": {
"yahoo-finance": {
"args": [
"mcp-yahoo-finance"
],
"command": "uvx"
}
}
}code --add-mcp '{"name":"yahoo-finance","args":["mcp-yahoo-finance"],"command":"uvx"}'[mcp_servers.yahoo-finance]
command = "uvx"
args = ["mcp-yahoo-finance"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/mcp-yahoo-finance to learn what the "MCP Yahoo Finance" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
npx @modelcontextprotocol/inspector uv run mcp-yahoo-financepip install mcp-yahoo-financeThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/mcp-yahoo-finance)Nothing comparable is listed yet.
v0.2.0Release notes0.1.4Release notes0.1.3Release notes0.1.2Release notes0.1.1Release notes0.1.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "mcp-yahoo-finance" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.