Yahoo Finance

Servidor MCP do Yahoo Finance

Um servidor Model Context Protocol (MCP) que fornece a assistentes de IA acesso a dados do Yahoo Finance via yfinance. Consulte informações de ações, notícias financeiras, rankings de setores e gere gráficos financeiros profissionais — tudo a partir do seu chat de IA.

Recursos

• Dados de Ações — Informações da empresa, financeiros, métricas de valuation, dividendos e dados de negociação
• Dados de Analistas — Metas de consenso, tendências de estimativas/revisões, histórico de recomendações e ações em nível de empresa
• Demonstrações Financeiras — Demonstração de resultados e balanço patrimonial com dados históricos (EBIT, Capital Investido, etc.)
• Notícias Financeiras — Artigos de notícias recentes e comunicados à imprensa para qualquer ticker
• Busca — Encontre ações, ETFs e notícias no Yahoo Finance
• Rankings de Setores — Principais ETFs, fundos mútuos, empresas, líderes de crescimento e melhores desempenhos por setor
• Histórico de Preços — Dados OHLCV históricos como tabelas Markdown ou gráficos profissionais
• Geração de Gráficos — Gráficos de candlestick, VWAP e perfil de volume retornados como imagens WebP
• Dados de Opções — Cadeias de opções com calls, puts, preços de exercício, IV e datas de vencimento
• Dados de Propriedade — Principais acionistas, investidores institucionais, detentores de fundos mútuos e transações de insiders
• Visão de Fundos — Participações de ETFs e fundos mútuos, classes de ativos, setores, ratings e detalhes operacionais
• Screeners — Árvores de consulta predefinidas, de ações, fundos mútuos e ETFs

Ferramentas

yfinance_get_ticker_info

Recupere dados abrangentes de ações, incluindo informações da empresa, financeiros, métricas de negociação e dados de governança.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação (ex.: AAPL, GOOGL, MSFT)

Retorna: Objeto JSON com detalhes da empresa, dados de preço, métricas de valuation, informações de negociação, dividendos, financeiros e indicadores de desempenho.

yfinance_get_analyst_price_targets

Busque o preço atual e as metas de preço de consenso dos analistas para uma ação.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação (ex.: AAPL, GOOGL, MSFT)

Retorna: Objeto JSON com campos de preço current, low, high, mean e median. A cobertura de analistas e os campos disponíveis variam conforme o símbolo.

yfinance_get_analyst_estimates

Busque estimativas de consenso de analistas, momentum de revisões, recomendações, estimativas de crescimento e histórico de lucros.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação
sections	array	Não	Qualquer um de recommendations, earnings_estimate, revenue_estimate, eps_trend, eps_revisions, earnings_history ou growth_estimates. Omita para todas as seções
max_rows	number	Não	Máximo de linhas por seção. Padrão: 12. Use 0 para todas as linhas

Retorna: Arrays nomeados para as seções disponíveis, além de _metadata contendo contagens de linhas por seção, status de truncamento, seções indisponíveis e seções com falha. Uma falha em uma seção não descarta seções buscadas com sucesso.

yfinance_get_upgrades_downgrades

Busque atualizações, rebaixamentos, iniciações, reiterações e mudanças de meta de preço de analistas, das mais recentes para as mais antigas.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação
max_rows	number	Não	Máximo de ações a retornar. Padrão: 25. Use 0 para retornar todas as linhas

Retorna: Objeto JSON contendo registros de upgrades_downgrades e _metadata com contagens de linhas e status de truncamento. Os registros podem incluir:

• GradeDate: Data e hora da ação do analista
• Firm: Nome da empresa de análise
• ToGrade e FromGrade: Ratings novo e anterior
• Action: Ação de rating
• priceTargetAction: Ação de meta de preço, como Raises, Lowers ou Maintains
• currentPriceTarget e priorPriceTarget: Metas de preço nova e anterior

Os campos disponíveis variam conforme o símbolo e a ação do analista.

yfinance_get_ticker_news

Busque artigos de notícias recentes e comunicados à imprensa para uma ação específica.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação

Retorna: Array JSON de itens de notícias com título, resumo, data de publicação, provedor, URL e miniatura.

yfinance_search

Pesquise no Yahoo Finance por ações, ETFs e artigos de notícias.

Parâmetro	Tipo	Obrigatório	Descrição
query	string	Sim	Consulta de busca — nome da empresa, símbolo do ticker ou palavras-chave
search_type	string	Sim	"all" (cotações + notícias), "quotes" (somente ações/ETFs) ou "news" (somente artigos)

Retorna: Cotações e/ou resultados de notícias correspondentes, dependendo de search_type.

yfinance_get_top

Obtenha as entidades financeiras mais bem classificadas dentro de um setor de mercado.

Parâmetro	Tipo	Obrigatório	Descrição
sector	string	Sim	Setor de mercado (veja setores suportados abaixo)
top_type	string	Sim	"top_etfs", "top_mutual_funds", "top_companies", "top_growth_companies" ou "top_performing_companies"
top_n	number	Não	Número de resultados a retornar (padrão: 10, máximo: 100)

Retorna: Array JSON das principais entidades com métricas relevantes.

Setores Suportados

Basic Materials, Communication Services, Consumer Cyclical, Consumer Defensive, Energy, Financial Services, Healthcare, Industrials, Real Estate, Technology, Utilities

yfinance_screen

Execute screeners do Yahoo Finance usando chaves de screener predefinidas ou árvores de consulta personalizadas.

Parâmetro	Tipo	Obrigatório	Descrição
query	string/objeto	Sim	Para query_type="predefined": chave de screener como "day_gainers". Para query_type="equity", "fund" ou "etf": árvore de consulta personalizada com nós {operator, operands}
query_type	string	Não	"predefined" (padrão), "equity", "fund" ou "etf"
offset	number	Não	Deslocamento de resultados
size	number	Não	Linhas para consultas personalizadas; o máximo do Yahoo é 250
count	number	Não	Linhas para consultas predefinidas; o máximo do Yahoo é 250
sort_field	string	Não	Campo de ordenação, por exemplo "percentchange"
sort_asc	boolean	Não	Ordenar crescente se true, decrescente se false
user_id	string	Não	Identificador de usuário opcional do Yahoo
user_id_type	string	Não	Tipo de ID de usuário opcional do Yahoo, comumente "guid"

Retorna: Resposta JSON do screener do Yahoo Finance, normalmente incluindo linhas de cotações e metadados.

Exemplo de screener de ações personalizado:

{
  "query_type": "equity",
  "query": {
    "operator": "and",
    "operands": [
      { "operator": "gt", "operands": ["percentchange", 3] },
      { "operator": "eq", "operands": ["region", "us"] },
      { "operator": "gte", "operands": ["intradayprice", 5] },
      { "operator": "gt", "operands": ["dayvolume", 500000] }
    ]
  },
  "sort_field": "percentchange",
  "sort_asc": false,
  "size": 50
}

Exemplo de screener de ETF personalizado:

{
  "query_type": "etf",
  "query": {
    "operator": "and",
    "operands": [
      { "operator": "eq", "operands": ["categoryname", "Large Blend"] },
      { "operator": "lte", "operands": ["annualreportnetexpenseratio", 0.2] }
    ]
  },
  "sort_field": "fundnetassets",
  "sort_asc": false,
  "size": 25
}

yfinance_screen_gappers

Execute um screener personalizado específico para ações com gap de alta na sessão de abertura.

Parâmetro	Tipo	Obrigatório	Descrição
min_percent_change	number	Não	Percentual mínimo de gap/variação em relação ao fechamento anterior (padrão: 3.0)
min_price	number	Não	Preço mínimo intradiário (padrão: 5.0)
min_volume	number	Não	Volume mínimo do dia (padrão: 500000)
min_market_cap	number	Não	Capitalização de mercado mínima intradiária em USD (padrão: 2000000000)
region	string	Não	Código de região do Yahoo (padrão: "us")
size	number	Não	Número de resultados (padrão: 50, máximo: 250)
offset	number	Não	Deslocamento de resultados para paginação (padrão: 0)
sort_asc	boolean	Não	Ordenar por percentchange crescente (true) ou decrescente (false, padrão)

Retorna: Resposta JSON do screener do Yahoo Finance.

yfinance_get_price_history

Busque dados históricos de preços e, opcionalmente, gere gráficos de análise técnica.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação
period	string	Não	Intervalo de tempo — 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max (padrão: 1mo)
interval	string	Não	Granularidade dos dados — 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo (padrão: 1d)
chart_type	string	Não	Gráfico a gerar (omita para dados tabulares)
prepost	boolean	Não	Incluir dados de pré-mercado e pós-mercado quando disponíveis (padrão: false; útil com solicitações intradiárias como period="1d", interval="1m")

Tipos de gráfico:

Valor	Descrição
"price_volume"	Gráfico de candlestick com barras de volume
"vwap"	Gráfico de preço com sobreposição de Preço Médio Ponderado por Volume
"volume_profile"	Gráfico de candlestick com distribuição de volume por nível de preço

Retorna:

• Sem chart_type: Tabela Markdown com colunas de Data, Abertura, Máxima, Mínima, Fechamento, Volume, Dividendos e Desdobramentos de Ações.
• Com chart_type: Imagem WebP codificada em Base64 para uso eficiente de tokens.

yfinance_get_financials

Busque demonstrações financeiras (demonstração de resultados, balanço patrimonial e fluxo de caixa) com dados históricos.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação
frequency	string	Não	"annual" (anual), "quarterly" (trimestral) ou "ttm" (últimos doze meses). Padrão: "annual"

Retorna: Objeto JSON com dados de demonstração de resultados, balanço patrimonial e fluxo de caixa para cada período de relatório.

• Campos da Demonstração de Resultados: EBIT, Lucro Líquido, Provisão de Impostos, Lucro Antes de Impostos, Despesa de Juros, Receita Total, Lucro Operacional, EBITDA, Lucro Normalizado
• Campos do Balanço Patrimonial: Patrimônio Líquido dos Acionistas, Dívida Total, Caixa e Equivalentes de Caixa, Capital Investido, Dívida Líquida, Ativos Totais, Passivos Totais Líquidos de Participação Minoritária, Ativos Tangíveis Líquidos, Valor Contábil Tangível
• Campos do Fluxo de Caixa: Fluxo de Caixa Operacional, Fluxo de Caixa Livre, Despesas de Capital, Lucro Líquido de Operações Continuadas, Depreciação e Amortização, Variação no Capital de Giro, Dividendos em Caixa Pagos

yfinance_get_holders

Busque principais acionistas, acionistas institucionais, detentores de fundos mútuos e dados de insiders.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação (ex.: AAPL, MSFT)
max_rows	number	Não	Máximo de linhas retornadas por seção de detentores. Padrão: 10. Use 0 para retornar todas as linhas
Retorna: Objeto JSON com:

• major_holders — Detalhamento agregado onde cada linha tem um rótulo index (ex.: insidersPercentHeld, institutionsPercentHeld, institutionsFloatPercentHeld, institutionsCount) e um Value
• institutional_holders — Investidores institucionais; registros normalmente incluem campos como Date Reported, Holder, Shares, Value, pctChange, pctHeld
• mutualfund_holders — Detentores de fundos mútuos; registros normalmente incluem campos semelhantes aos de detentores institucionais
• insider_transactions — Negociações recentes de insiders; registros normalmente incluem campos como Shares, Value, Insider, Position, Transaction, Start Date, Ownership
• insider_purchases — Resumo de seis meses onde cada linha descreve uma categoria (Compras, Vendas, Ações Líquidas, etc.); registros normalmente incluem campos como Insider Purchases Last 6m, Shares, Trans
• insider_roster — Insiders conhecidos; registros normalmente incluem campos como Name, Position, Shares Owned Directly, Most Recent Transaction, Latest Transaction Date
• _metadata — Metadados de limite de linhas com max_rows e por seção total_rows, returned_rows e truncated

As seções de detentores são limitadas a 10 linhas por padrão para manter as respostas concisas. Passe max_rows: 0 quando precisar dos conjuntos de dados completos de detentores. Os nomes dos campos para conjuntos de dados relacionados a detentores são fornecidos por yfinance e podem variar conforme o ticker, a disponibilidade de dados e a versão do yfinance.

yfinance_get_fund_data

Busca a composição de portfólio e detalhes operacionais de ETFs ou fundos mútuos.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker do ETF ou fundo mútuo (por exemplo, SPY, BND ou VFIAX)
sections	array	Não	Qualquer um de description, fund_overview, fund_operations, asset_classes, top_holdings, equity_holdings, bond_holdings, bond_ratings ou sector_weightings. Omita para todas as seções
max_rows	number	Não	Máximo de linhas por seção tabular. Padrão: 25. Use 0 para todas as linhas

Retorna: Seções de fundos disponíveis além de _metadata com limites de linhas, truncamento por seção, seções indisponíveis e seções com falha. A combinação de seções depende do fundo; por exemplo, fundos de ações e fundos de títulos expõem diferentes detalhamentos de portfólio.

yfinance_get_option_dates

Busca as datas de vencimento de opções disponíveis para uma ação.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação (ex.: AAPL, MSFT)

Retorna: Array JSON de datas de vencimento no formato AAAA-MM-DD.

yfinance_get_option_chain

Busca dados da cadeia de opções (calls e puts) para uma ação com preços de exercício disponíveis.

Parâmetro	Tipo	Obrigatório	Descrição
symbol	string	Sim	Símbolo do ticker da ação
expiration_date	string	Não	Data de vencimento da opção no formato AAAA-MM-DD. Omita para buscar todas as datas.
option_type	string	Não	"calls", "puts" ou "all" (padrão: "all")

Retorna: Objeto JSON organizado por data de vencimento, com dados de calls e/ou puts incluindo:

• contractSymbol: Identificador do contrato de opção
• strike: Preço de exercício
• lastPrice: Último preço negociado
• bid/ask: Preços de compra e venda (bid e ask)
• volume: Volume de negociação
• openInterest: Juros em aberto
• impliedVolatility: IV
• inTheMoney: Se a opção está ITM
• contractSize: Tamanho do contrato (REGULAR)
• currency: Moeda (USD)

Uso

Via uv (recomendado)

1. Instale o uv
2. Adicione o seguinte à configuração do seu cliente MCP:

{
  "mcpServers": {
    "yfmcp": {
      "command": "uvx",
      "args": ["yfmcp@latest"]
    }
  }
}

Via Docker

{
  "mcpServers": {
    "yfmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "narumi/yfinance-mcp"]
    }
  }
}

A partir do código-fonte

1. Clone o repositório e instale as dependências:

git clone https://github.com/narumiruna/yfinance-mcp.git
cd yfinance-mcp
uv sync

2. Adicione o seguinte à configuração do seu cliente MCP:

{
  "mcpServers": {
    "yfmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yfinance-mcp",
        "yfmcp"
      ]
    }
  }
}

Substitua /path/to/yfinance-mcp pelo caminho real do seu repositório clonado.

Testando com Codex CLI

Este repositório inclui .codex/config.toml, que registra o servidor MCP local yfmcp para Codex CLI usando uv run yfmcp. Após clonar o repositório e executar uv sync, abra o Codex CLI a partir da raiz do repositório e tente prompts como:

Show VOO ticker info
Show VOO price history for the last 5 days
Find the ticker symbol for Toyota
Get AAPL option expiration dates

Desenvolvimento

Pré-requisitos

• Python ≥ 3.12
• Gerenciador de pacotes uv

Configuração

uv sync --extra dev

Lint e Formatação

uv run ruff check .
uv run ruff format .

Verificação de Tipos

uv run ty check src tests

Teste

uv run pytest -v -s --cov=src tests

Chatbot de Demonstração

Veja o chatbot de demonstração em seu repositório dedicado: yfinance-mcp-demo

Contribuidores

Feito com contrib.rocks.

Licença

Este projeto é licenciado sob a Licença MIT.