Overview

This MCP server exposes real-time and historical stock data from yfinance through a Model Context Protocol (MCP)–compatible API. It wraps the yfinance Python library to present a small set of tools (search, quote, history) that model-driven agents, dashboards, and research tools can call using a standard tool-invocation pattern. Because it outputs structured JSON and follows MCP conventions, the server is easy to integrate into LLM agent chains and automated workflows.

You can use the server to fetch latest quotes, intraday and longer-term historical series, and symbol search results. The implementation focuses on practical developer ergonomics: simple HTTP endpoints, repeatable deployment via Docker, and minimal configuration so you can add live market context to agents and analytics processes quickly.

Features

MCP-compatible tool endpoints for model-driven tool invocation
Symbol search against public stock listing metadata
Real-time quotes (near real-time as provided by yfinance)
Historical time series with configurable period and interval (1m, 5m, 1d, etc.)
JSON responses optimized for machine consumption (agents, dashboards)
Simple local or containerized deployment
Example curl and Python snippets for quick integration

Installation / Configuration

Clone the repository, install dependencies, and run the server locally, or build and run the Docker image.

Local (virtual environment):

git clone https://github.com/Adity-star/mcp-yfinance-server.git
cd mcp-yfinance-server
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# Run with Uvicorn (example)
uvicorn main:app --host 0.0.0.0 --port 8000

Docker:

# Build
docker build -t mcp-yfinance-server .

# Run
docker run -p 8000:8000 \
  -e PORT=8000 \
  --name mcp-yfinance \
  mcp-yfinance-server

Common environment variables

PORT (default: 8000) — HTTP server port
LOG_LEVEL (default: info) — logging verbosity
CACHE_TTL (optional) — seconds to cache yfinance responses to reduce external calls

Adjust and export env vars before launching the container or process.

Available Resources

The server exposes MCP-style tools under a base path (example: /mcp). Each tool accepts a JSON payload describing the tool input and returns a structured JSON result.

Tool overview:

Tool name	Purpose	Input (example fields)	Output
search	Find tickers / symbols by company name	query (string), limit (int)	list of {symbol, name, exchange}
quote	Latest quote / snapshot for a symbol	symbol (string)	{symbol, price, bid, ask, timestamp, raw}
history	Historical time series for a symbol	symbol, period (e.g. “1mo”), interval (e.g. “5m”)	array of {timestamp, open, high, low, close, volume}

Example: list available tools

curl http://localhost:8000/mcp/tools
# returns JSON list of tool names and schemas

Execute a tool (generic example)

curl -X POST http://localhost:8000/mcp/run \
  -H "Content-Type: application/json" \
  -d '{"tool": "quote", "input": {"symbol": "AAPL"}}'

Example response (quote)

{
  "symbol": "AAPL",
  "price": 174.22,
  "bid": 174.20,
  "ask": 174.25,
  "timestamp": "2026-04-10T14:32:00Z",
  "raw": { /* raw yfinance payload */ }
}

Python client example

import requests

base = "http://localhost:8000/mcp"
resp = requests.post(f"{base}/run", json={
    "tool": "history",
    "input": {"symbol": "MSFT", "period": "5d", "interval": "1m"}
})
print(resp.json())

Use Cases

Agent tool for LLMs: Add the MCP server as a tool endpoint so an LLM can call quote or history during conversation to ground responses in current market data.
Dashboards and observability: Power financial dashboards with on-demand historical series and snapshots without embedding yfinance directly into the UI layer.
Research and backtesting: Programmatically fetch historical bars for backtests or feature engineering. Combine history outputs with your data pipeline.
Alerts and monitoring: Regularly poll quote for specific symbols and trigger alerts when price crosses thresholds.
Symbol discovery: Use search to map fuzzy company names or mentions to canonical tickers used by downstream systems.

Best Practices & Notes

yfinance draws from public data sources and may be delayed or rate-limited. Use caching (CACHE_TTL) for non-critical bulk requests.
For high-frequency or production trading, rely on market-data vendors and licensed feeds; this server is intended for dashboards, agents, and research rather than high-volume execution.
Validate tool inputs in your calling code (symbol format, allowed intervals) to avoid unnecessary external calls.
Run the server behind a reverse proxy or API gateway if exposing it publicly; add authentication if you plan to share access across teams.

If you want to extend the server, add additional MCP tools (e.g., options chains, financials) by implementing new handlers that use yfinance data and expose them in the tools registry.

MCP Server YFinance Real-Time & Historical Stock Data