YFinance MCP Server

A fully-featured Model Context Protocol (MCP) server that exposes nearly all of Yahoo Finance’s capabilities through simple, typed MCP tools.
Built with FastMCP so you can plug it straight into any LLM workflow, agent framework, or the official MCP client SDK.

---

Features

• 25+ tools covering:
  • Price history (single & multiple tickers)
  • Financial statements (income, balance sheet, cash-flow)
  • Analyst data (recommendations, price targets, earnings estimates)
  • Ownership & insider transactions
  • Dividends, splits & actions
  • Options chains
  • News & earnings calendar
  • Fund / ETF holdings
  • ESG & sustainability metrics
  • Stock screeners & search utilities
  • Batch operations & yfinance global configuration
• Pure-Python, zero external services required.
• Exposes both STDIO (default) and HTTP/SSE transports if you want to serve over the network.

---

Requirements

• Python 3.10+
• pipx (for MCP client integration)

All dependencies are listed in requirements.txt (generated below).

pandas
yfinance
fastmcp

If you already installed packages manually you can skip the next step.

Installing pipx

If you don't have pipx installed, install it first:

macOS:

brew install pipx

Linux/Ubuntu:

sudo apt install pipx
# or
python3 -m pip install --user pipx

Windows:

python -m pip install --user pipx

After installation, ensure pipx is in your PATH:

pipx ensurepath

---

Installation

Option 1: Install from PyPI (Recommended)

pip install yfinance-mcp-server

Option 2: Install from source

# 1) Clone the repository
git clone https://github.com/itsmejay80/yfinance-mcp-server.git
cd yfinance-mcp-server

# 2) (Optional) create a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3) Install dependencies
pip install -r requirements.txt

---

Running the server

If installed from PyPI:

yfinance-mcp-server

If running from source:

python main.py

You should see a FastMCP banner like:

╭─ FastMCP 2.0 ─────────────────────────╮
│ 🖥️  Server name:     yfinance-server   │
│ 📦 Transport:       STDIO             │
│ …                                     │
╰───────────────────────────────────────╯

The server listens on STDIO by default (perfect for embedding inside other processes).
To expose an HTTP endpoint instead:

from fastmcp import FastMCP
from main import mcp  # reuse the configured server

if __name__ == "__main__":
    # Starts an HTTP server on http://0.0.0.0:8000
    mcp.run(transport="http", host="0.0.0.0", port=8000)

---

Configuration for MCP Clients

Cursor IDE

Add this to your Cursor MCP settings:

{
  "mcpServers": {
    "yfinance": {
      "command": "pipx",
      "args": [
        "run",
        "yfinance-mcp-server"
      ]
    }
  }
}

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "yfinance": {
      "command": "pipx",
      "args": [
        "run",
        "yfinance-mcp-server"
      ]
    }
  }
}

Custom Configuration

If you installed from source or need custom paths:

{
  "mcpServers": {
    "yfinance-server": {
      "command": "python",
      "args": ["/path/to/yfinance-mcp-server/main.py"],
      "cwd": "/path/to/yfinance-mcp-server"
    }
  }
}

---

Consuming the tools

From Python using the FastMCP client

from fastmcp import FastMCPClient

client = FastMCPClient("http://localhost:8000")

# List available tools
for tool in client.list_tools():
    print(tool.name, "->", tool.description)

# Call a tool
resp = client.call_tool("get_stock_history", {
    "symbol": "AAPL",
    "period": "6mo",
    "interval": "1d"
})
print(resp)

From the command line (stdio)

You can pipe JSON-RPC requests into the running process; most users will instead let an agent framework manage this. See FastMCP docs for details.

---

Project structure

MCPWorld/
├── main.py          # all tool definitions + entrypoint
├── requirements.txt # dependency list
└── README.md        # you are here

---

Deployment

The server is self-contained—any platform that can run Python can host it.
For one-command deployment, check out FastMCP Cloud.

---

License

This project is licensed under the MIT License (see LICENSE file, if included). Feel free to adapt or extend.