yfinance-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
yfinance-mcp
Servidor MCP (Model Context Protocol) que expõe os dados do Yahoo Finance
através da biblioteca yfinance,
construído com FastAPI + FastMCP e pronto para deploy na Vercel.
Arquitetura
yfinance-mcp/
├── api/
│ └── index.py # entrypoint serverless da Vercel (importa app.main:app)
├── app/
│ ├── main.py # FastAPI app; monta o servidor MCP em /mcp
│ ├── mcp_server.py # instância FastMCP + registro das tools
│ ├── tools/
│ │ ├── company.py # get_company_info, get_fast_info, get_isin
│ │ ├── price.py # histórico, dividendos, splits, shares
│ │ ├── financials.py # DRE, balanço, fluxo de caixa
│ │ ├── holders.py # holders institucionais/insiders
│ │ ├── analysis.py # recomendações, estimativas, calendário, news
│ │ ├── options.py # opções (calls/puts)
│ │ └── market.py # download multi-ticker, search, lookup, market status
│ └── utils/
│ ├── ticker_cache.py # cache de yf.Ticker por símbolo
│ └── serialization.py # conversão de DataFrame/Series/numpy -> JSON
├── requirements.txt
├── vercel.json
└── .python-versionO servidor MCP roda em modo stateless HTTP (stateless_http=True), ideal
para ambientes serverless como a Vercel, onde cada invocação pode cair em uma
instância diferente (sem estado de sessão compartilhado entre requisições).
Related MCP server: Yahoo Finance MCP Server
Tool principal
get_company_info(ticker: str)
Retorna o perfil completo da empresa/ativo: nome, setor, indústria,
resumo do negócio, site, país, número de funcionários, métricas de
valuation (P/L, EV/EBITDA, PEG, P/VP), dados de preço (atual, máxima/mínima
52 semanas, volume), dividendos (yield, payout ratio, data ex-dividendo),
margens, preço-alvo dos analistas, e todos os demais campos do Ticker.info
do yfinance.
get_company_info(ticker="AAPL")
get_company_info(ticker="PETR4.SA") # ações da B3Demais tools (40 no total)
Categoria | Tools |
Empresa |
|
Preço/histórico |
|
Demonstrações financeiras |
|
Ownership |
|
Análise/Analistas |
|
Opções |
|
Mercado (multi-ticker) |
|
Todas as tools têm docstrings detalhadas (visíveis para o cliente MCP) e
aceitam o parâmetro ticker no formato do Yahoo Finance (ex.: AAPL,
PETR4.SA, ^GSPC, BTC-USD).
Rodando localmente
py -3.12 -m venv .venv
source .venv/Scripts/activate # Windows (git bash) — no PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt # apenas dependências de runtime
# ou, para desenvolver (testes + lint):
pip install -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000Healthcheck:
GET http://localhost:8000/healthInfo do serviço:
GET http://localhost:8000/Endpoint MCP (streamable-http):
http://localhost:8000/mcpDocs REST auto-geradas (rotas não-MCP):
http://localhost:8000/docs
Testando a tool principal com o cliente fastmcp:
import asyncio
from fastmcp import Client
async def main():
async with Client("http://localhost:8000/mcp") as client:
result = await client.call_tool("get_company_info", {"ticker": "AAPL"})
print(result.data)
asyncio.run(main())Testes e qualidade de código
O projeto tem suíte de testes unitários (pytest) cobrindo 100% do código em
app/ e lint (pylint) configurado para o código de aplicação e para os
testes (com regras separadas — ver .pylintrc e tests/.pylintrc).
Nenhum teste bate na Yahoo Finance de verdade: cada teste substitui
get_ticker (ou a função/classe correspondente do módulo yfinance) por um
dublê (tests/conftest.py::FakeTicker e fakes locais), então a suíte roda
rápida, determinística e sem depender de rede ou de rate limit da Yahoo.
pip install -r requirements-dev.txt
# rodar todos os testes
pytest
# com relatório de cobertura
pytest --cov=app --cov-report=term-missing
# lint do código de aplicação (api/index.py, app/**)
pylint app api
# lint dos testes (regras um pouco mais permissivas: sem exigir
# docstring por teste, permite classes "fake" com poucos métodos)
pylint --rcfile=tests/.pylintrc testsEstrutura dos testes:
Arquivo | Cobre |
| conversão DataFrame/Series/numpy → JSON, NaN/NaT, Timestamp |
| helper |
| cache de |
| rotas não-MCP do FastAPI ( |
| cada tool individualmente, com yfinance mockado |
| round-trip real via protocolo MCP (transporte em memória) |
CI (GitHub Actions)
O workflow em .github/workflows/ci.yml roda em todo push/PR para main:
pylint app api— lint do código de aplicação (deve ficar em 10.00/10).pylint --rcfile=tests/.pylintrc tests— lint dos testes.pytest --cov=app --cov-fail-under=90— testes com gate mínimo de 90% de cobertura (o projeto está em 100%).
Deploy na Vercel
O projeto já inclui vercel.json apontando para api/index.py (que expõe o
app do FastAPI), usando o builder @vercel/python.
npm i -g vercel # se ainda não tiver a CLI
vercel login
vercel # deploy de preview
vercel --prod # deploy de produçãoApós o deploy, o endpoint MCP ficará em:
https://<seu-projeto>.vercel.app/mcpObservações importantes para produção
Timeout de função: chamadas ao Yahoo Finance podem levar alguns segundos (principalmente
download_historycom vários tickers ouget_option_chain). No plano Hobby da Vercel o timeout padrão é curto (~10s); se necessário, aumente omaxDurationda função no painel do projeto ou faça upgrade de plano.Rate limiting do Yahoo Finance: o yfinance consulta endpoints não oficiais do Yahoo Finance; uso excessivo pode ser temporariamente limitado (HTTP 429). Não há chave de API necessária.
Cold start: como é serverless, a primeira requisição após um período de inatividade pode ser mais lenta.
Conectando em um cliente MCP (ex.: Claude Desktop / Claude Code)
Adicione um servidor MCP remoto (HTTP) apontando para a URL publicada:
{
"mcpServers": {
"yfinance": {
"url": "https://<seu-projeto>.vercel.app/mcp"
}
}
}Ou, via Claude Code CLI:
claude mcp add --transport http yfinance https://<seu-projeto>.vercel.app/mcpTratamento de erros
Erros do yfinance (ticker inválido, sem dados disponíveis, falha de rede)
propagam como erro de tool do MCP (isError: true) com a mensagem original,
permitindo que o cliente/LLM trate o caso adequadamente.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Yahoo Finance for AI agents: quotes, price history, options with Greeks, financials, news, movers.
Yahoo Finance stock quotes and multi-ticker comparison as agent tools.
Scrape stock quotes, historical prices, and financial statements from Yahoo Finance.
Unofficial Finnhub MCP — wraps Finnhub Stock API (finnhub.io)
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides financial data from Yahoo Finance via MCP, enabling AI agents to access real-time stock info, historical prices, financial statements, and market analysis.1014-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to access Yahoo Finance data including stock information, news, price history, options, and earnings via MCP tools.54MIT
- AlicenseAqualityDmaintenanceEnables querying stock data, financial information, news, and historical prices from Yahoo Finance through a set of MCP tools.5MIT
- AlicenseAqualityBmaintenanceMCP server that exposes Yahoo Finance data through tools for searching instruments, fetching quotes, history, company info, financials, dividends, news, recommendations, and options. Enables AI assistants to answer market-data questions using natural language.24726 PyPI3MIT