Indian Stock Analyst MCP

stock-analyst-mcp

Servidor MCP para análise do mercado de ações global — fundamentos, análises técnicas, avaliação DCF, comparação entre pares, suporte multi-ativos e muito mais. Funciona em mais de 50 regiões no mundo todo.

Novidades na v0.5.7

Requisito Python 3.13+

• Requer Python >=3.13: Corrige uvx que selecionava Python 3.12 desatualizado, causando falhas na extensão C do pandas (ModuleNotFoundError: pandas._libs.pandas_parser)
• uvx stock-analyst-mcp agora funciona sem --python: uv/uvx seleciona automaticamente 3.13+

Novidades na v0.5.6

Migração do Framework MCP — FastMCP standalone

• Substituiu o SDK mcp pelo fastmcp standalone: Elimina as mudanças que quebram compatibilidade da v2.0.0, sem mais erros de importação mcp.server.fastmcp
• Dependência mais limpa: fastmcp>=3.4.0,<4.0.0 (mantido pela Prefect, em desenvolvimento ativo)
• Configuração de porta: Agora passada como kwarg para mcp.run(transport=..., port=...)
• À prova de futuro: Sem conflitos de versão do SDK, o fastmcp lida com todas as versões do protocolo MCP

Novidades na v0.5.5

Correção de Notícias — mudança de formato do yfinance

• Corrigiu manchetes vazias: o yfinance agora aninha os campos de notícias sob content
• Mapeamento correto: title, publisher, link, pub_date extraídos de content.*
• Compatível com versões anteriores: ainda lida com o formato legado de notícias de nível superior

Novidades na v0.5.4

Correção de API — compatibilidade com FastMCP.run()

• Corrigiu TypeError: FastMCP.run() não aceita o kwarg port
• Configuração de porta: Definida via mcp.settings.port antes de chamar run()

Novidades na v0.5.3

Correção de Compatibilidade — suporte a mcp>=1.28

• Corrigiu importação que quebrava: Substituiu o MCPServer removido por FastMCP de mcp.server.fastmcp
• Dependência mcp fixada: mcp>=1.0.0,<3.0.0 para evitar quebras futuras
• Adicionado requirements.txt para instalações baseadas em pip

Novidades na v0.5.2

Correção do Screener — screen_stocks funciona em todas as regiões

• Corrigiu o parâmetro EquityQuery do yfinance: _size → size na chamada yf.screen(), restaurando os resultados do screener para a Índia e outras regiões

Novidades na v0.5.1

Revisão de Desempenho — análise de pares 3-19x mais rápida

• Fundamentos de pares em paralelo: ThreadPoolExecutor nas chamadas get_info() (3,7x mais rápido)
• Downloads de histórico em lote: Um único yf.download() para todos os pares (19,3x mais rápido)
• Busca de trechos em paralelo: A análise de notícias agora busca trechos de artigos simultaneamente
• Novo módulo stock_analyst/utils/: Utilitários de concorrência reutilizáveis (parallel_map, parallel_map_dict, batch_download_history)
• Zero novas dependências: Usa concurrent.futures da stdlib

Exemplo: analisar LOW (EUA) com 10 pares agora leva ~2-3s em vez de 8-10s.

Instalação

pip install stock-analyst-mcp

Ou execute diretamente sem instalar:

uvx stock-analyst-mcp

Configuração do MCP

Adicione à configuração do seu cliente MCP (Claude Desktop, Devin, Cursor, etc.):

{
  "mcpServers": {
    "stock-analyst": {
      "command": "uvx",
      "args": ["stock-analyst-mcp"]
    }
  }
}

Ou se instalado via pip:

{
  "mcpServers": {
    "stock-analyst": {
      "command": "stock-analyst-mcp"
    }
  }
}

Ferramentas

Ferramenta	Descrição
analyze_stock	Análise completa: fundamentos + técnicos + pares + DCF + previsão + notícias (qualquer região)
get_fundamentals	Indicadores financeiros: lucratividade, liquidez, alavancagem, eficiência, avaliação
get_technicals	Sinais técnicos: tendência EMA, RSI, MACD, Bandas de Bollinger
get_peer_comparison	Métricas fundamentais + técnicas de pares com rankings (por região)
get_dcf_valuation	DCF: WACC, valor patrimonial/ação, faixa de sensibilidade
get_revenue_forecast	Previsão de receita: cenários base/otimista/pessimista
get_news	Manchetes de notícias com sentimento VADER + trechos de artigos + recomendações de analistas
get_market_mood	Índices específicos da região + índice de volatilidade + avaliação de mercado
screen_stocks	Filtrar ações por critérios (setor, P/L, ROE, capitalização de mercado, etc.) em qualquer região
get_screener_filters	Listar chaves de filtro e opções de ordenação disponíveis no screener
search_tickers	Buscar tickers por nome ou símbolo em várias regiões (ações, ETFs, índices, cripto, etc.)
analyze_asset	Analisar qualquer classe de ativo: ações, ETFs, índices, commodities, cripto, moedas
compare_stocks	Comparação lado a lado de múltiplas ações
get_raw_data	Buscar dados financeiros brutos em cache para análises aprofundadas
get_config	Visualizar as configurações atuais de todas as ferramentas de análise
set_config	Atualizar configurações dinamicamente

Ferramentas de Configuração

get_config

Recupera todas as configurações atuais. Útil para entender quais parâmetros estão disponíveis antes de chamar set_config.

from stock_analyst import get_config

config = get_config()
# Returns dict with sections:
# - data_provider, default_exchange, default_period, cache settings
# - technical_analysis: EMA periods, RSI period, MACD params, Bollinger settings
# - financial_analysis: DCF params, WACC settings, forecast scenarios
# - peer_comparison: max count, metrics to compare
# - output: format, pretty-print settings

set_config

Atualiza a configuração dinamicamente sem reiniciar. As alterações afetam chamadas subsequentes de ferramentas.

from stock_analyst import set_config

# Change technical analysis period from 1y to 1d
result = set_config("default_period", "1d")
# Returns: {"status": "success", "key": "default_period", "new_value": "1d", "affected_tools": ["all_tools"]}

# Change RSI period from 14 to 21
result = set_config("ta_rsi_period", "21")
# Returns: {"status": "success", "key": "ta_rsi_period", "new_value": 21, "affected_tools": ["get_technicals", "analyze_stock"]}

# Change DCF projection years from 5 to 10
result = set_config("fa_dcf_projection_years", "10")
# Returns: {"status": "success", "key": "fa_dcf_projection_years", "new_value": 10, "affected_tools": ["get_dcf_valuation", "get_revenue_forecast", "analyze_stock"]}

Chaves de Configuração Comuns:

Chave	Tipo	Padrão	Descrição	Afeta
default_period	str	1y	Período histórico: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, max	all_tools
ta_rsi_period	int	14	Período de cálculo do RSI	get_technicals, analyze_stock
ta_ema_periods	str	20,50,200	Períodos EMA separados por vírgula	get_technicals, analyze_stock
ta_macd_params	str	12,26,9	MACD (rápido, lento, sinal)	get_technicals, analyze_stock
ta_bollinger_enabled	bool	true	Habilitar Bandas de Bollinger	get_technicals, analyze_stock
ta_bollinger_period	int	20	Período das Bandas de Bollinger	get_technicals, analyze_stock
fa_dcf_enabled	bool	true	Executar avaliação DCF	analyze_stock, get_dcf_valuation
fa_dcf_projection_years	int	5	Anos de projeção do DCF	get_dcf_valuation, get_revenue_forecast, analyze_stock
fa_dcf_terminal_growth	float	0.025	Taxa de crescimento terminal (2,5%)	get_dcf_valuation, analyze_stock
fa_dcf_exit_multiple	float	12.0	Múltiplo de saída para DCF	get_dcf_valuation, analyze_stock
fa_wacc_risk_free_rate	float	0.07	Taxa livre de risco (7% para a Índia)	get_dcf_valuation, analyze_stock
fa_wacc_equity_risk_premium	float	0.06	Prêmio de risco de ações (6%)	get_dcf_valuation, analyze_stock
fa_wacc_cost_of_debt	float	0.09	Custo da dívida (9% para a Índia)	get_dcf_valuation, analyze_stock
fa_wacc_tax_rate	float	0.25	Alíquota de impostos (25% para a Índia)	get_dcf_valuation, analyze_stock
peers_max_count	int	10	Máximo de pares para comparar	get_peer_comparison, analyze_stock
cache_ttl	int	3600	TTL do cache em segundos	all_tools

Exemplo: Personalizar Análise Técnica

from stock_analyst import set_config, get_technicals

# Use 1-day data with custom RSI period
set_config("default_period", "1d")
set_config("ta_rsi_period", "21")

# Get technicals with new settings
signals = get_technicals("RELIANCE")

Exemplo: Personalizar Avaliação DCF

from stock_analyst import set_config, get_dcf_valuation

# Use 10-year projection with different growth assumptions
set_config("fa_dcf_projection_years", "10")
set_config("fa_dcf_terminal_growth", "0.03")  # 3% terminal growth
set_config("fa_wacc_risk_free_rate", "0.065")  # 6.5% risk-free rate

# Get DCF with new assumptions
valuation = get_dcf_valuation("RELIANCE")

CLI

Também funciona como CLI autônoma (sem necessidade de LLM):

# Full analysis
stock-analyst --symbol RELIANCE

# Specific analysis
stock-analyst --symbol TCS --analysis fundamentals
stock-analyst --symbol INFY --analysis technicals
stock-analyst --symbol RELIANCE --analysis dcf

# Compare multiple stocks
stock-analyst --symbols RELIANCE,TCS,INFY --compare

# Markdown output
stock-analyst --symbol RELIANCE --format markdown

# Raw data
stock-analyst --symbol RELIANCE --raw financials

# Market mood (no symbol needed)
stock-analyst --analysis market-mood

# Stock screener (India)
stock-analyst --screen --sector Technology --pe-max 30 --roe-min 0.15
stock-analyst --screen --market-cap-min 50000000000 --sort-by pe --limit 20

# Global stocks (any region)
stock-analyst --symbol AAPL --region us
stock-analyst --symbol 0700.HK --region hk
stock-analyst --screen --region gb --sector Technology --pe-max 25

# Market mood (global)
stock-analyst --analysis market-mood --region us
stock-analyst --analysis market-mood --region de

# Ticker search
stock-analyst --search "Apple" --search-type stock --region us
stock-analyst --search "Bitcoin" --search-type cryptocurrency

# Multi-asset analysis
stock-analyst --symbol SPY --analysis asset --asset-type etf
stock-analyst --symbol GC=F --analysis asset --asset-type commodity
stock-analyst --symbol BTC-USD --analysis asset --asset-type crypto

Configuração

Todas as configurações podem ser definidas via variáveis de ambiente com o prefixo SA_. Os padrões funcionam imediatamente para o mercado indiano (NSE). Suporta mais de 50 regiões no mundo.

Variável	Padrão	Descrição
SA_DEFAULT_REGION	in	Código da região (us, gb, de, jp, in, etc.)
SA_DEFAULT_EXCHANGE	.NS	NSE (.NS) ou BSE (.BO) — apenas para a Índia
SA_DEFAULT_PERIOD	1y	Período de dados históricos
SA_CACHE_BACKEND	redis	redis, csv ou none
SA_REDIS_URL	redis://localhost:6379/0	URL de conexão do Redis
SA_CACHE_TTL	3600	TTL do cache em segundos
SA_SCREENER_ENABLED	true	Usar screener.in como fallback para pares
SA_FA_DCF_ENABLED	true	Executar avaliação DCF
SA_FA_WACC_RISK_FREE_RATE	0.07	Rendimento do título público indiano de 10 anos
SA_PEERS_MAX_COUNT	10	Máximo de pares para comparar
SA_MCP_TRANSPORT	stdio	stdio ou streamable-http
SA_MCP_PORT	3001	Porta para streamable-http

Consulte configurations.env.example para a lista completa.

Biblioteca Python

from stock_analyst import (
    analyze, get_fundamentals, get_technicals,
    get_news, get_market_mood, screen_stocks,
    search_tickers, analyze_asset,
)

# Indian stocks (default region)
result = analyze("RELIANCE")
ratios = get_fundamentals("TCS")
signals = get_technicals("INFY", period="6mo")

# Global stocks (any region)
us_stock = analyze("AAPL", region="us")
hk_stock = analyze("0700.HK", region="hk")
uk_stock = analyze("HSBA", region="gb")

# News with sentiment
news = get_news("TCS")
# Returns headlines with sentiment_score, sentiment_label, snippet

# Market mood (region-specific)
mood_in = get_market_mood(region="in")  # Includes MMI from tickertape
mood_us = get_market_mood(region="us")  # S&P 500 + VIX
mood_de = get_market_mood(region="de")  # DAX + VDAX

# Stock screener (any region)
results_in = screen_stocks({"sector": "Technology", "pe_max": 30}, region="in")
results_us = screen_stocks({"sector": "Technology", "pe_max": 40}, region="us")

# Ticker search
apple_results = search_tickers("Apple", instrument_type="stock", region="us")
crypto_results = search_tickers("Bitcoin", instrument_type="cryptocurrency")

# Multi-asset analysis
etf = analyze_asset("SPY", asset_type="etf")
commodity = analyze_asset("GC=F", asset_type="commodity")
crypto = analyze_asset("BTC-USD", asset_type="crypto")
currency = analyze_asset("EURUSD=X", asset_type="currency")

Testes

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=stock_analyst --cov-report=term-missing

# Run specific test file
pytest tests/test_peers.py -v

Fontes de Dados

• yfinance — OHLCV, demonstrações financeiras, balanço patrimonial, fluxo de caixa, informações, descoberta de pares via Industry API, screener de ações via EquityQuery (50+ regiões)
• screener.in — descoberta de pares + fallback do screener de ações para a Índia (melhor esforço, degradação graciosa)
• tickertape.in — scraping do Market Mood Index (MMI) para a Índia
• VADER — análise de sentimento de manchetes (vaderSentiment)
• Padrões ajustados para a Índia — taxa livre de risco 7%, custo da dívida 9%, impostos 25%

Regiões Suportadas

Mais de 50 regiões via yfinance: EUA, Reino Unido, Alemanha, França, Itália, Espanha, Holanda, Bélgica, Suíça, Áustria, Suécia, Noruega, Dinamarca, Finlândia, Polônia, República Tcheca, Romênia, Portugal, Grécia, Hungria, Irlanda, Lituânia, Letônia, Estônia, Canadá, México, Brasil, Argentina, Chile, Peru, Colômbia, Venezuela, Austrália, Nova Zelândia, Japão, Coreia do Sul, China, Hong Kong, Singapura, Malásia, Tailândia, Filipinas, Indonésia, Vietnã, Paquistão, Sri Lanka, EAU, Arábia Saudita, Kuwait, Catar, Israel, Egito, Turquia, África do Sul e mais.

Referência Rápida de Regiões

Região	Código	Índice Principal	VIX
EUA	us	S&P 500 (^GSPC)	^VIX
Reino Unido	gb	FTSE 100 (^FTSE)	^VIX
Alemanha	de	DAX (^GDAXI)	^VDAX
França	fr	CAC 40 (^FCHI)	^VDAX
Japão	jp	Nikkei 225 (^N225)	^VIX
Hong Kong	hk	Hang Seng (^HSI)	^VIX
Índia	in	Nifty 50 (^NSEI)	^INDIAVIX
Austrália	au	ASX 200 (^AXJO)	^VIX
Canadá	ca	TSX (^GSPTSE)	^VIX
Brasil	br	Bovespa (^BVSP)	^VIX

Licença

MIT