# 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](https://gofastmcp.com) 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:**
```bash
brew install pipx
```
**Linux/Ubuntu:**
```bash
sudo apt install pipx
# or
python3 -m pip install --user pipx
```
**Windows:**
```bash
python -m pip install --user pipx
```
After installation, ensure pipx is in your PATH:
```bash
pipx ensurepath
```
---
## Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install yfinance-mcp-server
```
### Option 2: Install from source
```bash
# 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:
```bash
yfinance-mcp-server
```
### If running from source:
```bash
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:
```python
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:
```json
{
"mcpServers": {
"yfinance": {
"command": "pipx",
"args": [
"run",
"yfinance-mcp-server"
]
}
}
}
```
### Claude Desktop
Add this to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"yfinance": {
"command": "pipx",
"args": [
"run",
"yfinance-mcp-server"
]
}
}
}
```
### Custom Configuration
If you installed from source or need custom paths:
```json
{
"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
```python
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
```text
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](https://fastmcp.cloud).
---
## License
This project is licensed under the MIT License (see `LICENSE` file, if included). Feel free to adapt or extend.
Raw data
{
"_id": null,
"home_page": null,
"name": "yfinance-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, yfinance, yahoo-finance, stocks, financial-data",
"author": null,
"author_email": "Jayesh <jaypatel6963@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c2/61/2300b098bbde5113dc255beee0a5354000cd5de40eb6c71ea978335709a9/yfinance_mcp_server-1.0.4.tar.gz",
"platform": null,
"description": "# YFinance MCP Server\n\nA fully-featured **Model Context Protocol (MCP)** server that exposes nearly all of Yahoo Finance\u2019s capabilities through simple, typed MCP tools. \nBuilt with [FastMCP](https://gofastmcp.com) so you can plug it straight into any LLM workflow, agent framework, or the official MCP client SDK.\n\n---\n\n## Features\n\n* 25+ tools covering:\n * Price history (single & multiple tickers)\n * Financial statements (income, balance sheet, cash-flow)\n * Analyst data (recommendations, price targets, earnings estimates)\n * Ownership & insider transactions\n * Dividends, splits & actions\n * Options chains\n * News & earnings calendar\n * Fund / ETF holdings\n * ESG & sustainability metrics\n * Stock screeners & search utilities\n * Batch operations & yfinance global configuration\n* Pure-Python, zero external services required.\n* Exposes both **STDIO** (default) and **HTTP/SSE** transports if you want to serve over the network.\n\n---\n\n## Requirements\n\n* Python 3.10+\n* **pipx** (for MCP client integration)\n\nAll dependencies are listed in `requirements.txt` (generated below).\n\n```\npandas\nyfinance\nfastmcp\n```\n\n> If you already installed packages manually you can skip the next step.\n\n### Installing pipx\n\nIf you don't have pipx installed, install it first:\n\n**macOS:**\n```bash\nbrew install pipx\n```\n\n**Linux/Ubuntu:**\n```bash\nsudo apt install pipx\n# or\npython3 -m pip install --user pipx\n```\n\n**Windows:**\n```bash\npython -m pip install --user pipx\n```\n\nAfter installation, ensure pipx is in your PATH:\n```bash\npipx ensurepath\n```\n\n---\n\n## Installation\n\n### Option 1: Install from PyPI (Recommended)\n\n```bash\npip install yfinance-mcp-server\n```\n\n### Option 2: Install from source\n\n```bash\n# 1) Clone the repository\ngit clone https://github.com/itsmejay80/yfinance-mcp-server.git\ncd yfinance-mcp-server\n\n# 2) (Optional) create a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# 3) Install dependencies\npip install -r requirements.txt\n```\n\n---\n\n## Running the server\n\n### If installed from PyPI:\n```bash\nyfinance-mcp-server\n```\n\n### If running from source:\n```bash\npython main.py\n```\n\nYou should see a FastMCP banner like:\n\n```\n\u256d\u2500 FastMCP 2.0 \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n\u2502 \ud83d\udda5\ufe0f Server name: yfinance-server \u2502\n\u2502 \ud83d\udce6 Transport: STDIO \u2502\n\u2502 \u2026 \u2502\n\u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n```\n\nThe server listens on **STDIO** by default (perfect for embedding inside other processes). \nTo expose an HTTP endpoint instead:\n\n```python\nfrom fastmcp import FastMCP\nfrom main import mcp # reuse the configured server\n\nif __name__ == \"__main__\":\n # Starts an HTTP server on http://0.0.0.0:8000\n mcp.run(transport=\"http\", host=\"0.0.0.0\", port=8000)\n```\n\n---\n\n## Configuration for MCP Clients\n\n### Cursor IDE\n\nAdd this to your Cursor MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"yfinance\": {\n \"command\": \"pipx\",\n \"args\": [\n \"run\",\n \"yfinance-mcp-server\"\n ]\n }\n }\n}\n```\n\n### Claude Desktop\n\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"yfinance\": {\n \"command\": \"pipx\",\n \"args\": [\n \"run\",\n \"yfinance-mcp-server\"\n ]\n }\n }\n}\n```\n\n### Custom Configuration\n\nIf you installed from source or need custom paths:\n\n```json\n{\n \"mcpServers\": {\n \"yfinance-server\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/yfinance-mcp-server/main.py\"],\n \"cwd\": \"/path/to/yfinance-mcp-server\"\n }\n }\n}\n```\n\n---\n\n## Consuming the tools\n\n### From Python using the FastMCP client\n\n```python\nfrom fastmcp import FastMCPClient\n\nclient = FastMCPClient(\"http://localhost:8000\")\n\n# List available tools\nfor tool in client.list_tools():\n print(tool.name, \"->\", tool.description)\n\n# Call a tool\nresp = client.call_tool(\"get_stock_history\", {\n \"symbol\": \"AAPL\",\n \"period\": \"6mo\",\n \"interval\": \"1d\"\n})\nprint(resp)\n```\n\n### From the command line (stdio)\n\nYou can pipe JSON-RPC requests into the running process; most users will instead let an agent framework manage this. See FastMCP docs for details.\n\n---\n\n## Project structure\n\n```text\nMCPWorld/\n\u251c\u2500\u2500 main.py # all tool definitions + entrypoint\n\u251c\u2500\u2500 requirements.txt # dependency list\n\u2514\u2500\u2500 README.md # you are here\n```\n\n---\n\n## Deployment\n\nThe server is self-contained\u2014any platform that can run Python can host it. \nFor one-command deployment, check out [FastMCP Cloud](https://fastmcp.cloud).\n\n---\n\n## License\n\nThis project is licensed under the MIT License (see `LICENSE` file, if included). Feel free to adapt or extend.\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive yfinance MCP server providing access to Yahoo Finance data",
"version": "1.0.4",
"project_urls": {
"Bug Reports": "https://github.com/yourusername/yfinance-mcp-server/issues",
"Homepage": "https://github.com/yourusername/yfinance-mcp-server",
"Source": "https://github.com/yourusername/yfinance-mcp-server"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" yfinance",
" yahoo-finance",
" stocks",
" financial-data"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a8446c29008717f807db1ffac2b007e75816d03d202019d54487ecb72ddccb72",
"md5": "70e5fb3573d70d9772ec3fa90fd4e02f",
"sha256": "7b00b294e1178722d78ad19eb2310df16a852d275b8714a2a560a4f590f5a2f9"
},
"downloads": -1,
"filename": "yfinance_mcp_server-1.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "70e5fb3573d70d9772ec3fa90fd4e02f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9165,
"upload_time": "2025-07-13T21:40:58",
"upload_time_iso_8601": "2025-07-13T21:40:58.911495Z",
"url": "https://files.pythonhosted.org/packages/a8/44/6c29008717f807db1ffac2b007e75816d03d202019d54487ecb72ddccb72/yfinance_mcp_server-1.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c2612300b098bbde5113dc255beee0a5354000cd5de40eb6c71ea978335709a9",
"md5": "fb6b5a7c5da2fc644441c77ba575e388",
"sha256": "db1b953e52a6f63e3d553e5b294f505702bf80882732c3c74f913755269471b3"
},
"downloads": -1,
"filename": "yfinance_mcp_server-1.0.4.tar.gz",
"has_sig": false,
"md5_digest": "fb6b5a7c5da2fc644441c77ba575e388",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 13267,
"upload_time": "2025-07-13T21:41:00",
"upload_time_iso_8601": "2025-07-13T21:41:00.123957Z",
"url": "https://files.pythonhosted.org/packages/c2/61/2300b098bbde5113dc255beee0a5354000cd5de40eb6c71ea978335709a9/yfinance_mcp_server-1.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 21:41:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "yfinance-mcp-server",
"github_not_found": true,
"lcname": "yfinance-mcp-server"
}
JSON
