MCP Yahoo Finance

MCP Yahoo Finance

Um servidor Model Context Protocol (MCP) para Yahoo Finance. Ele fornece ferramentas para preços, informações de empresas, dados históricos, demonstrações financeiras, notícias, recomendações, lucros, dividendos e opções.

mcp-yahoo-finance está em desenvolvimento inicial. Os nomes das ferramentas e os campos de resposta podem mudar entre versões.

Instalação

Você pode executar mcp-yahoo-finance sem uma instalação separada usando uvx.

Usando pip

Usando pip.

pip install mcp-yahoo-finance

Usando Git

Você também pode instalar o pacote após clonar o repositório para sua máquina.

git clone git@github.com:maxscheijen/mcp-yahoo-finance.git
cd mcp-yahoo-finance
uv sync

Configuração

Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

{
    "mcpServers": {
        "yahoo-finance": {
            "command": "uvx",
            "args": ["mcp-yahoo-finance"]
        }
    }
}

Você também pode usar docker:

{
    "mcpServers": {
        "yahoo-finance": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "IMAGE"]
        }
    }
}

VSCode

Adicione isto ao seu .vscode/mcp.json:

{
    "servers": {
        "yahoo-finance": {
            "command": "uvx",
            "args": ["mcp-yahoo-finance"]
        }
    }
}

Exemplos de perguntas

1. "Qual é o preço da ação da Apple?"
2. "Me dê uma cotação completa para AAPL com o fechamento anterior, intervalo intradiário e status do mercado."
3. "Mostre-me a visão geral da empresa Nvidia."
4. "Qual é a diferença no preço das ações entre Apple e Google?"
5. "Quanto o preço da ação da Apple mudou entre 2024-01-01 e 2025-01-01?"
6. "Quais são as datas de vencimento de opções disponíveis para AAPL?"
7. "Mostre-me a cadeia de opções para AAPL com vencimento em 2024-01-19"
8. "Quais são as opções de compra e venda para Tesla?"

Formato de resposta

As chamadas de ferramenta retornam dados estruturados compatíveis com JSON. Por exemplo, uma cotação completa se parece com isto:

{
  "symbol": "AAPL",
  "currentPrice": 243.5822,
  "previousClose": 241.33,
  "absoluteChange": 2.2522,
  "percentChange": 0.9331,
  "open": 242.1,
  "dayHigh": 244.2,
  "dayLow": 241.9,
  "volume": 45678901,
  "marketStatus": "REGULAR",
  "currency": "USD",
  "exchange": "NMS",
  "timestamp": "2025-01-02T15:30:00+00:00",
  "source": {
    "provider": "Yahoo Finance",
    "endpoint": "info",
    "fetchedAt": "2025-01-02T15:30:01+00:00"
  }
}

Erros usam o mesmo formato para todas as ferramentas e são marcados como erros MCP:

{
  "error": {
    "code": "NO_DATA",
    "message": "No historical data found for AAPL"
  }
}

Resultados históricos e tabulares mantêm seus nomes de colunas e incluem datas como strings de data de calendário YYYY-MM-DD. Isso é verdadeiro tanto para índices Yahoo Finance ingênuos quanto com reconhecimento de fuso horário; o fuso horário do provedor não é exposto. Ferramentas de preço histórico, de data única e de intervalo de datas retornam preços ajustados por padrão (ajustes de desdobramento e dividendos). get_historical_stock_prices aceita adjusted: false quando valores OHLC não ajustados são necessários. Uma consulta de data única e um intervalo de datas usam datas de calendário inclusivas; fins de semana e feriados de mercado retornam um erro estruturado NO_DATA quando não existe linha de negociação. Campos ausentes de cotação e visão geral da empresa são representados como null. Notícias são limitadas a 10 artigos por padrão (até 100), normaliza título, URL, editor, miniatura, símbolos relacionados e publishedAt como um carimbo de data/hora UTC ISO 8601, e aceita filtros opcionais inclusivos start_date e end_date. Recomendações, lucros, dividendos, demonstrações e opções usam o mesmo campo de nível superior symbol e retornam dados no formato do provedor quando disponíveis.

Ferramentas disponíveis

O servidor expõe estas ferramentas. Os valores symbol usam símbolos de ticker do Yahoo Finance, como AAPL ou MSFT.

Ferramenta	Finalidade
get_current_stock_price	Preço atual e metadados de cotação
get_rich_quote	Instantâneo de cotação normalizado com preço, variação, intervalo da sessão, status do mercado e metadados de origem
get_company_overview	Perfil de empresa normalizado com setor, indústria, capitalização de mercado, site, número de funcionários, descrição e metadados de origem
get_symbol_comparison	Comparação de cotação atual para até 20 símbolos
get_performance_analysis	Retornos multi-símbolos limitados, médias móveis, volatilidade, rebaixamento, retorno relativo ao benchmark e correlação
get_stock_price_by_date	Preço de fechamento ajustado para uma data de negociação
get_stock_price_date_range	Preços de fechamento ajustados para um intervalo de datas inclusivo
get_historical_stock_prices	Preços históricos por período e intervalo
get_dividends	Histórico de dividendos
get_stock_splits	Histórico de desdobramentos de ações
get_capital_gains	Distribuições de ganhos de capital
get_upcoming_dividends	Próximas datas e taxas de dividendos
get_earnings_analytics	Surpresas e estimativas de lucros
get_income_statement	Demonstração de resultados por frequência anual, trimestral ou contínua
get_cashflow	Demonstração de fluxo de caixa por frequência
get_earning_dates	Datas de lucros recentes e futuras
get_news	Notícias Yahoo Finance limitadas e normalizadas com filtros de data opcionais
get_recommendations	Recomendações de analistas
get_option_expiration_dates	Vencimentos de opções disponíveis
get_option_chain	Opções de compra e venda limitadas para uma data de vencimento com filtros de preço de exercício, moneyness, liquidez, spread, tipo e contagem
get_option_summary	Volatilidade implícita, juros em aberto, volume, índices de compra/venda e resumo de dor máxima para um vencimento

A análise de desempenho usa fechamentos ajustados por desdobramento e dividendos. O retorno total é (last close / first close) - 1; a volatilidade anualizada é o desvio padrão dos retornos diários multiplicado por sqrt(252); o rebaixamento máximo é o rebaixamento mínimo a partir de um pico contínuo. Correlações usam retornos diários em datas de negociação compartilhadas, portanto símbolos com calendários desiguais permanecem comparáveis.

Desenvolvimento local

Instale o ambiente de desenvolvimento travado com uv sync, depois execute:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build

O Makefile fornece atalhos para os comandos comuns:

make test
make lint
make docker-build

A suíte de testes simula o Yahoo Finance e não faz solicitações ao provedor em tempo real.

Build

Crie a imagem Docker com:

docker build -t mcp-yahoo-finance .

Testar com MCP Inspector

npx @modelcontextprotocol/inspector uv run mcp-yahoo-finance

Limitações do Yahoo Finance

Os dados do Yahoo Finance são fornecidos por terceiros e podem estar atrasados, incompletos ou indisponíveis. Este projeto não fornece aconselhamento de investimento e não garante a precisão, integridade ou atualidade dos dados retornados. Verifique valores importantes em uma fonte confiável antes de confiar neles.