Content
# Yahoo Finance MCP Server
A [FastMCP](https://gofastmcp.com) server that exposes Yahoo Finance stock
data as MCP tools, via the [`yfinance`](https://github.com/ranaroussi/yfinance)
library.
No API key is required — `yfinance` talks to Yahoo Finance's public,
undocumented endpoints using an anonymous cookie/crumb token that it fetches
automatically. This is unofficial and can break or get rate-limited if Yahoo
changes their frontend, but no signup or credentials are needed.
## Tools
| Tool | Description |
|---|---|
| `get_current_price` | Current price of a stock by ticker or company name |
| `get_historical_data` | Historical OHLCV data (default: past 5 years) |
| `get_trend` | Trend direction, moving averages, momentum, volatility |
| `get_price_stats` | Change stats over a custom number of recent trading days (e.g. "average change over the last 10 days") |
| `get_sector_companies` | Top companies in a sector/industry/theme (e.g. "AI", "semiconductors", "banks"), with live price data |
| `get_stock_news` | Latest news headlines for a stock |
| `research_stock` | Bundles trend + recent activity + news in one call, for research/outlook-style questions |
All tools accept either a ticker symbol (`AAPL`) or a company name (`Apple`) — names are resolved to tickers automatically via Yahoo's search endpoint.
## Project layout
```
src/yfinance_mcp/
app.py # shared FastMCP instance
resolve.py # ticker / sector / theme resolution (pure logic)
server.py # entrypoint (reads transport from env, runs mcp)
tools/
quotes.py # get_current_price
history.py # get_historical_data, get_trend, get_price_stats
sectors.py # get_sector_companies
news.py # get_stock_news
research.py # research_stock
tests/ # unit tests for pure computation logic (no network)
.github/workflows/ # CI: runs pytest on push/PR
```
Each tool module separates the pure computation (e.g. `compute_trend`,
`compute_price_stats` in `history.py`) from the network fetch, so the math can
be unit tested with synthetic data without hitting Yahoo Finance.
## Local setup
```bash
cd yfinance-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```
Run tests:
```bash
.venv/bin/pytest
```
Run the server (stdio transport, for local MCP clients):
```bash
.venv/bin/yfinance-mcp
# or: .venv/bin/python -m yfinance_mcp.server
```
### Claude Desktop config
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"yahoo-finance": {
"command": "/absolute/path/to/yfinance-mcp/.venv/bin/yfinance-mcp"
}
}
}
```
## Deploying on an EC2 instance (remote/HTTP access)
`stdio` transport only works when the MCP client spawns the process locally.
To reach the server remotely from an EC2 box, run it over HTTP instead.
### 1. Provision the instance
- Any small instance works (e.g. `t3.micro`/`t3.small`), Amazon Linux 2023 or Ubuntu 22.04+.
- In the instance's **security group**, only open the port you'll run on (default `8000`) to trusted IPs — do not open it to `0.0.0.0/0` unless you put auth/TLS in front of it (see step 5).
### 2. Install dependencies
```bash
sudo yum install -y python3 python3-pip git # Amazon Linux
# or: sudo apt update && sudo apt install -y python3 python3-venv git # Ubuntu
git clone <your-repo-url> yfinance-mcp
cd yfinance-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
```
### 3. Run over HTTP
The server reads `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT` env vars:
```bash
MCP_TRANSPORT=http MCP_PORT=8000 .venv/bin/yfinance-mcp
```
This serves the MCP endpoint at `http://<ec2-public-ip>:8000/mcp`. Test it:
```bash
curl -X POST http://<ec2-public-ip>:8000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```
### 4. Keep it running with systemd
Create `/etc/systemd/system/yfinance-mcp.service`:
```ini
[Unit]
Description=Yahoo Finance MCP Server
After=network.target
[Service]
Type=simple
User=ec2-user
WorkingDirectory=/home/ec2-user/yfinance-mcp
Environment=MCP_TRANSPORT=http
Environment=MCP_HOST=0.0.0.0
Environment=MCP_PORT=8000
ExecStart=/home/ec2-user/yfinance-mcp/.venv/bin/yfinance-mcp
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
Then:
```bash
sudo systemctl daemon-reload
sudo systemctl enable --now yfinance-mcp
sudo systemctl status yfinance-mcp
journalctl -u yfinance-mcp -f # tail logs
```
### 5. (Recommended) put it behind Nginx + TLS
The server has no built-in authentication — anyone who can reach the port can
call the tools. For anything beyond a locked-down security group, put it
behind Nginx as a reverse proxy with TLS (via Let's Encrypt/certbot) and
basic auth or an allowlist, then point clients at `https://your-domain/mcp`
instead of the raw port. Keep the security group closed to the internet and
only open port 443 on the reverse proxy.
### 6. Connect a remote MCP client
Any MCP client that supports HTTP/streamable-HTTP transport can connect using
the server URL, e.g. `https://your-domain/mcp` or `http://<ec2-ip>:8000/mcp`.
Consult your specific client's docs for how it accepts a remote MCP server URL
(config varies by client).
## License
MIT — see [LICENSE](LICENSE).
