screener-mcp

Transforme o Claude em um analista de ações indiano pessoal, alimentado por dados ao vivo do Screener.in.

Documentação

screener-mcp

Um servidor MCP (Model Context Protocol) que dá ao Claude acesso em tempo real a dados do Screener.in, NSE e MCX — transformando o Claude em um assistente de pesquisa para ações indianas.

Reportar um problema · LinkedIn · logeshl2003@gmail.com

screener-mcp conecta o Claude (Claude Code, Claude Desktop ou qualquer cliente MCP) a dados de ações indianas: demonstrativos financeiros de empresas, triagem de ações, relatórios anuais, teleconferências de resultados, comunicados corporativos e um rastreador de portfólio local. Aponte o Claude para uma empresa ou um filtro, e ele fará a pesquisa usando dados reais e atuais em vez do conhecimento de seus dados de treinamento sobre a ação.

O que você pode fazer

"Compare ITC and HINDUNILVR on all key ratios"
"Find low-debt, high-ROCE chemical stocks"
"Quality stocks within 10% of their 52-week low"
"Has MSUMI fallen more than the auto sector over the last 60 days?"
"What are analysts' target prices for TMPV, and what's the latest news?"
"Summarize the key risks from Reliance's 2024 annual report"
"What did TCS management say about margins in Q3FY25?"
"What are the red flags in Asian Paints?"
"Show me recent NSE announcements for HDFCBANK"
"Find recent bulk deals in a stock"
"Track my portfolio and show live P&L"
"Save a research note on TITAN — strong Q3, watch margins"

Início rápido

Requer uv — pip install uv ou brew install uv.

claude mcp add screener -s user -- uvx --from 'screener-mcp[ai]' screener-mcp

Isso instala o servidor completo, incluindo análise de documentos (relatórios anuais, teleconferências de resultados). Se você precisar apenas de pesquisa de empresas e triagem de ações, remova o extra para uma instalação muito mais leve:

claude mcp add screener -s user -- uvx screener-mcp

Núcleo vs. [ai]: o pacote base cobre dados de empresas, triagem, comunicados da NSE e rastreamento de portfólio. O extra [ai] adiciona pdfplumber, chromadb e sentence-transformers (~1–2GB, via torch) para alimentar ask_company_research e search_market_commentary (e a parte de orientação da administração de get_forward_outlook). Sem ele, essas ferramentas retornam um erro de "não instalado" — todo o resto funciona normalmente.

Usando Claude Desktop em vez de Claude Code? Veja Configuração do Claude Desktop.

Verifique se funciona

claude mcp list
# screener  stdio  Connected

Depois tente alguns prompts no Claude:

"Search for Asian Paints"
"Give me the company overview for TCS"
"Run the defense theme screen"

Se eles retornarem dados reais, o servidor está funcionando de ponta a ponta.

O que ele oferece

Pesquisa de empresas — demonstrativos financeiros (incl. P/L, P/VPA, ROE e histórico de dívida/patrimônio líquido no fim do ano), tendências de participação acionária com avaliação de promotor/penhor, comparação entre pares, verificações de bandeiras vermelhas baseadas em regras (sem necessidade de login)
Triagem de ações — consultas personalizadas no estilo Screener.in com AND / OR / parênteses, filtros temáticos pré-construídos (temas de setores partem das empresas realmente presentes no setor) e cláusulas técnicas (distância de 52 semanas, RSI, DMA, picos de volume). Linhas de lixo são filtradas por padrão. Filtros fundamentais exigem login gratuito no Screener.in; filtros apenas técnicos não exigem
Contexto de movimento de preço — ações de qualidade próximas às mínimas de 52 semanas em uma única chamada, e o movimento de uma ação vs. seu índice setorial e o Nifty 50
Contexto de valuation e qualidade — P/L e ROCE vs. a mediana do setor para até 20 ações de uma vez, e proxies de fosso: participação de receita, classificação, concentração do setor e quão duráveis têm sido os retornos e margens
Visão prospectiva e do mercado — estimativas de EPS/receita de analistas e preços-alvo, vitórias de pedidos e arquivamentos de capex, orientação da administração em teleconferências de resultados e notícias recentes
Análise de documentos — faça perguntas sobre relatórios anuais e transcrições de teleconferências de resultados usando um pipeline RAG local
Eventos corporativos — comunicados da NSE (incl. ações de rating de crédito e ESG), negociações em bloco por empresa ou investidor, divulgações de negociação de insiders
Mercado e pesquisa — contexto de preços de commodities, notas de pesquisa locais
Portfólio — um rastreador privado e local de participações com P&L em tempo real

30 ferramentas no total — referência completa abaixo. Cada ferramenta retorna o mesmo envelope de resposta, então dados parciais ou degradados são sempre explícitos.

Fluxos de trabalho de exemplo

Comparar empresas — "Compare ITC and HINDUNILVR on all key ratios" → compare_companies
Triar oportunidades — "Find low-debt, high-ROCE small caps" → screen_by_theme ou screen_stocks
Encontrar correções — "High-ROCE, low-debt stocks near their 52-week low" → get_52_week_low_candidates, ou screen_stocks("Return on capital employed > 15 AND 52 week low distance < 10")
Mercado vs. específico da empresa — "Is this fall sector-wide or just this stock?" → compare_to_sector
O que o mercado acha — "Analyst targets and recent news for TMPV" → get_analyst_targets, get_recent_news
Está barato para o setor? — "Which of these 15 stocks trade below their industry P/E?" → get_relative_valuation, ou screen_stocks(..., peer_relative=True)
Verificação de fosso — "Is MSUMI a market leader with durable returns?" → get_moat_signals
Crescimento futuro — "What's the order pipeline and guidance for BEL?" → get_forward_outlook
Ler um relatório anual — "What are the key risks in Reliance's 2024 annual report?" → ask_company_research(..., year=2024)
Ler uma teleconferência de resultados — "What did TCS say about margins in Q3FY25?" → ask_company_research(..., quarter="Q3FY25")
Entre anos — "How has ITC described cigarette taxation over the years?" → ask_company_research(..., doc_type="annual_report")
Detectar bandeiras vermelhas — "What are the red flags in Asian Paints?" → analyze_red_flags
Acompanhar atividade da NSE — "Show recent announcements for HDFCBANK" → get_company_announcements
Pesquisar negociações em bloco — "Any recent bulk deals in TITAN?" → get_bulk_deals("TITAN"); "What has SBI Mutual Fund bought in bulk?" → get_bulk_deals(name="SBI Mutual Fund")
Acompanhar um portfólio — "Add 10 shares of INFY at ₹1500 to my portfolio" → add_portfolio_stock
Salvar pesquisa — "Save a note on TITAN — strong Q3, watch margins" → notebook_ai

Arquitetura

Claude (Code / Desktop)
        │  MCP
        ▼
  screener-mcp
        │
        ├──► Screener.in   (financials, ratios, screening, industry pages, price history)
        ├──► NSE India     (announcements, order wins, bulk deals, insider trades)
        ├──► Yahoo Finance (analyst consensus & estimates, commodity benchmarks)
        └──► Google News   (recent headlines, broker target mentions)
        │
        ▼
  Research data (parsed, cached, indexed)
        │
        ▼
  Claude reasons over the data and answers

screener-mcp busca e normaliza os dados; o Claude faz a análise e explica em linguagem simples.

Opções de instalação

Claude Code

Use os comandos claude mcp add acima. Confirme com claude mcp list.

Claude Desktop

O Claude Desktop não lê claude mcp add — edite o arquivo de configuração diretamente.

1. Instale uv se necessário: brew install uv (ou pip install uv)

2. Abra o arquivo de configuração:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

(No aplicativo: Configurações → Desenvolvedor → Editar Configuração.)

3. Adicione o servidor screener:

{
  "mcpServers": {
    "screener": {
      "command": "uvx",
      "args": ["--from", "screener-mcp[ai]", "screener-mcp"],
      "env": {
        "SCREENER_USERNAME": "your@email.com",
        "SCREENER_PASSWORD": "yourpassword"
      }
    }
  }
}

O Claude Desktop não herda o ambiente do seu shell, então as credenciais devem ir no bloco "env" aqui — veja Credenciais. Deixe "env" totalmente de fora se você quiser apenas as ferramentas de pesquisa de empresas sem login.

spawn uvx ENOENT ao iniciar? O Claude Desktop inicia com um PATH mínimo. Execute which uvx e use o caminho absoluto (ex.: /opt/homebrew/bin/uvx) como "command".

4. Saia completamente do Claude Desktop (Cmd+Q no macOS) e reabra.

5. Verifique o ícone de ferramentas no compositor de mensagens — screener deve listar suas 30 ferramentas. Depois pergunte: "Search for Asian Paints".

Servidor não aparecendo? Verifique Configurações → Desenvolvedor para o status e os logs em ~/Library/Application Support/Claude/logs/mcp-server-screener.log (macOS) ou %APPDATA%\Claude\logs\ (Windows). JSON inválido — geralmente uma vírgula sobrando — faz o Claude Desktop pular todos os servidores silenciosamente.

pip / PyPI

O pacote está publicado no PyPI como screener-mcp. uvx (acima) o executa sem instalação persistente; para instalá-lo em um ambiente:

pip install screener-mcp          # core
pip install "screener-mcp[ai]"    # with document analysis

Depois execute diretamente, ou aponte claude mcp add para o ponto de entrada screener-mcp que ele instala.

Desenvolvedor (clone local)

git clone https://github.com/LogeshR15/screener-mcp
cd screener-mcp
python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

claude mcp add screener -s user -- \
  $(pwd)/.venv/bin/python3.11 \
  $(pwd)/run_server.py

Qualquer Python 3.11+ funciona — ex.: python3.12 -m venv .venv — basta apontar claude mcp add para esse interpretador. pip install -e . falhando com "editable mode currently requires a setuptools-based build"? Atualize pip no venv primeiro (como acima) e tente novamente.

Já clonou e está usando Claude Desktop? Aponte a configuração para o interpretador do seu venv em vez de uvx:

{
  "mcpServers": {
    "screener": {
      "command": "/absolute/path/to/screener-mcp/.venv/bin/python3.11",
      "args": ["/absolute/path/to/screener-mcp/run_server.py"]
    }
  }
}

Avançado: HTTP e Docker

Para implantação remota/rede em vez de um processo stdio local, veja Servidor HTTP remoto e Docker abaixo.

Credenciais

Capacidade	Precisa de login no Screener.in?
Pesquisa de empresas (demonstrativos, índices, participação acionária, pares, bandeiras vermelhas)	Não
Triagem de ações com cláusulas fundamentais (`screen_stocks`, `screen_by_theme`)	Sim
Filtros apenas técnicos, `get_52_week_low_candidates`, `compare_to_sector`	Não (um login permite que `get_52_week_low_candidates` escaneie o mercado inteiro em vez de um índice)
`get_relative_valuation`, `get_moat_signals`, `get_forward_outlook`, `get_analyst_targets`, `get_recent_news`	Não (a orientação de teleconferência de resultados de `get_forward_outlook` precisa do extra `[ai]`)
Comunicados da NSE, negociações em bloco, ratings de crédito, commodities	Não
Análise de documentos, notebook, portfólio	Não

Para habilitar a triagem:

1. Registre-se gratuitamente em screener.in/register

2. Claude Code / execuções manuais — adicione a ~/.zshrc ou ~/.bashrc, depois recarregue (source ~/.zshrc) e reinicie o Claude Code:

export SCREENER_USERNAME="your@email.com"
export SCREENER_PASSWORD="yourpassword"

3. Claude Desktop — ele não lê seu perfil de shell, então os mesmos dois valores devem ir no bloco "env" de claude_desktop_config.json (veja Configuração do Claude Desktop):

"env": {
  "SCREENER_USERNAME": "your@email.com",
  "SCREENER_PASSWORD": "yourpassword"
}

Nunca envie credenciais reais — os valores acima são placeholders.

Ferramentas — 30 no total

Agrupadas por categoria. Veja Fluxos de trabalho de exemplo para as que você mais usará.

Pesquisa de Empresas

Ferramenta	O que faz	Login necessário
`search_company`	Encontra empresa por nome ou símbolo	Não
`get_company_overview`	Índices-chave, preço, faixa de 52 semanas, códigos NSE/BSE, sobre, prós/contras do Screener	Não
`get_financials`	DRE (TTM separado) / Balanço Patrimonial / Fluxo de Caixa / Índices incl. P/L, P/VPA, ROE, dívida/patrimônio líquido no fim do ano	Não
`get_quarterly_results`	Últimos 8 trimestres de resultados	Não
`get_shareholding_pattern`	Tendências de participação de 8 trimestres por categoria, detecção de grupo promotor, penhor de promotor	Não
`get_peer_comparison`	Tabela de comparação entre pares do setor	Não
`compare_companies`	2–6 ações lado a lado, com bandeiras vermelhas pontuais; painel interativo (MCP App) onde suportado, JSON em qualquer lugar	Não
`get_full_analysis`	Todos os dados combinados para análise profunda (mesmas janelas das ferramentas independentes)	Não
`analyze_red_flags`	Verificações de bandeiras vermelhas baseadas em regras sobre todo o histórico, cada uma com evidências e limites	Não

Triagem de Ações

Ferramenta	O que faz	Login necessário
`screen_stocks`	Consulta Screener.in mais cláusulas técnicas (distância de 52 semanas, RSI, DMA, pico de volume)	Apenas cláusulas fundamentais
`get_52_week_low_candidates`	Filtros de qualidade + proximidade da mínima de 52 semanas, com campos de visão geral por correspondência	Não
`get_relative_valuation`	P/L e ROCE vs. a mediana do setor para até 20 ações de uma vez	Não
`compare_to_sector`	Retorno da ação vs. seu índice setorial e Nifty 50, com veredito mercado-vs-empresa	Não
`screen_by_theme`	Filtros temáticos pré-construídos — os critérios de cada tema estão na descrição da ferramenta	Apenas temas de consulta

Análise de Documentos

Ferramenta	O que faz	Dependências extras necessárias
`get_document_list`	Lista relatórios anuais e transcrições de teleconferências de resultados	Não
`ask_company_research`	Faça uma pergunta sobre os relatórios anuais e teleconferências de resultados de uma empresa — todos os recentes, um `doc_type`, ou um documento (`year` / `quarter` / `pdf_url`)	Sim
`search_market_commentary`	Pesquise uma pergunta nos documentos já indexados de várias empresas de uma vez	Sim

ask_company_research e search_market_commentary usam o mesmo cache — o primeiro indexa os documentos de uma empresa e os pesquisa (um ou muitos); o segundo pesquisa apenas o que já está indexado em vários símbolos (bom para "quais dessas empresas mencionaram Y?").

Eventos Corporativos

Ferramenta	O que faz	Login necessário
`get_company_announcements`	Comunicados corporativos da NSE com filtro de categoria — incl. `credit_rating` (CRISIL/ICRA/CARE/India Ratings) e `esg_rating`	Não
`get_bulk_deals`	Negociações em bloco da NSE por empresa (`symbol`), por investidor (`name`), ou ambos	Não
`get_insider_trading`	Divulgações de negociação SEBI PIT de promotores/KMP/pessoas designadas, sem limite de tamanho (ambos os feeds PIT da NSE mesclados)	Não

Mercado e Pesquisa

Ferramenta	O que faz	Login necessário
`get_recent_news`	Manchetes de notícias recentes de uma empresa (Google News), mais recentes primeiro	Não
`get_analyst_targets`	Preço-alvo de consenso (média/mediana/máximo/mínimo, número de analistas, divisão de classificação) + alvos de corretoras em manchetes recentes	Não
`get_forward_outlook`	Estimativas de EPS/receita de analistas, ganhos de pedidos e arquivamentos de capex, orientação da administração da última teleconferência de resultados	Não (`[ai]` para orientação)
`get_moat_signals`	Participação de receita/classificação e concentração do setor (HHI), além de ROCE, margem e durabilidade da participação do promotor	Não
`get_commodity_prices`	Preço de referência internacional, movimentos do período, preço aproximado em INR + símbolos das empresas expostas (incl. trigo; tabaco e polpa de madeira apenas como exposição)	Não
`notebook_ai`	Salvar, ler e resumir com IA notas de pesquisa localmente	Não

Portfólio

Ferramenta	O que faz	Login necessário
`add_portfolio_stock`	Adicionar/mesclar uma posição ao seu portfólio local (custo médio ponderado por quantidade)	Não
`update_portfolio_stock`	Sobrescrever quantidade/preço médio em uma posição existente (venda parcial, correção de custo)	Não
`remove_portfolio_stock`	Remover uma posição completamente	Não
`get_portfolio`	Visualizar posições com preço ao vivo, P&L (₹ e %) e peso	Não

Armazenado localmente em ~/.screener-mcp/portfolio.json — sem conta, sem serviço externo, nada sai da sua máquina.

Análise de documentos

A análise de documentos (extra [ai]) usa um pipeline RAG local:

ask_company_research("TCS", "What are the key risks?", year=2024)

  1. Fetch PDF link from Screener.in / NSE
  2. Download and parse with pdfplumber — two-column pages are split at the
     gutter, rotated/mirrored decorative text is dropped
  3. Chunk into 500-word overlapping segments
  4. Embed with sentence-transformers (runs locally, no API key needed)
  5. Store in ChromaDB (~/.screener-mcp/chroma_db/)
  6. Semantic search, re-ranked: question keywords boosted, BRSR boilerplate
     demoted (unless the question is about ESG), one hit per ~3-page window
  7. Return the top excerpts, each trimmed to ~900 characters around the
     question's terms, with document and page

Os resultados são armazenados em cache — o mesmo relatório não é baixado ou processado novamente. Índices criados por uma versão mais antiga do pipeline são reconstruídos automaticamente no próximo uso (a partir do PDF em cache). O freshness de cada documento relata last_indexed_at, o content_sha256 do PDF, seu etag / last_modified e source_changed (uma verificação HEAD contra o PDF ao vivo; null quando o servidor não fornece validadores). Se um relatório foi revisado ou reenviado, passe force_reindex=True para reconstruir o índice. O manifesto está em ~/.screener-mcp/index_manifest.json.

Triagem de ações

Temas pré-construídos

Consultas de temas executam uma consulta do Screener em todo o mercado:

undervalued_small_cap       Small caps < ₹5000 Cr, ROCE > 15%, low debt, P/E < 20
high_roce_low_debt          ROCE > 20%, debt to equity < 0.3
compounders                 15%+ growth: revenue, profit, ROE, ROCE
turnaround                  Strong recent profit recovery
rising_profit_falling_price Profit up 15%+/yr over 3 years, price down over 1 year, P/E < 15
improving_roce              ROCE > 15% and above last year's and its 5-year average
hidden_gems                 Small cap, high ROCE, strong growth
dividend_aristocrats        Yield > 2%, dividend paid in each of the last 2 years, 3y payout > 20%
qarp                        Quality at reasonable price
micro_cap_growth            High-growth micro caps < ₹1000 Cr

Temas de setor começam pelas empresas realmente no setor — a linguagem de consulta do Screener não tem campo de setor — e depois filtram:

defense                     Nifty India Defence + Aerospace & Defense and Shipbuilding industries
ev_theme                    Nifty EV & New Age Automotive constituents
chemicals                   Specialty Chemicals industry + Nifty Chemicals
railways                    Railway Wagons industry + a curated list of railway PSUs/suppliers
renewable_energy            Curated list of wind/solar makers and green power producers

Cada resultado diz de qual universo veio (data.universe), e a descrição de screen_by_theme carrega os critérios exatos de cada tema. Tanto screen_by_theme quanto screen_stocks aceitam page para ir além da primeira página de resultados.

Sintaxe de triagem personalizada

Market Capitalization < 5000 AND Return on capital employed > 15 AND Debt to equity < 0.5
Profit growth 5Years > 20 AND Sales growth 5Years > 15 AND Debt to equity < 0.3
Dividend yield > 3 AND Return on equity > 15 AND Pledged percentage < 5

Operadores suportados: > < >= <= =, combinados com AND, OR e parênteses

Lista completa de campos em CONTRIBUTING.md.

Cláusulas técnicas

Combine-as com cláusulas fundamentais usando AND, OR e parênteses:

52 week low distance < 10        % above the 52-week low
52 week high distance > 30       % below the 52-week high
RSI < 30                         14-day RSI
Price above 200 DMA              also below / 20, 50, 200 DMA / "50 DMA above 200 DMA"
Price vs 50 DMA < -5             % above (+) or below (−) a moving average
Volume vs 20 day average > 2     today's volume ÷ 20-day average volume

Return on capital employed > 15 AND Debt to equity < 0.5 AND 52 week low distance < 10
RSI < 30 AND Price above 200 DMA                          (technical-only: no login needed)
(Return on capital employed > 20 OR Return on equity > 25) AND Price above 200 DMA
Return on capital employed > 15 AND (RSI < 30 OR 52 week low distance < 5)

Cláusulas fundamentais rodam no Screener.in como de costume. As cláusulas técnicas são então avaliadas contra até max_candidates (padrão 150) dessas correspondências, usando histórico diário de preços da API pública de gráficos do Screener. Uma consulta com apenas cláusulas técnicas escaneia um índice NSE em vez disso (universe, padrão nifty500; também nifty50, midcap100, smallcap100, smallcap250, bank, it, auto, pharma, fmcg, metal, realty, energy, defence, chemicals, ...). Se alguns candidatos não foram verificados, a resposta tem partial: true e um reason. A faixa de 52 semanas é baseada em preços de fechamento.

Quando grupos de OR não contêm cláusulas técnicas, eles vão para o Screener inalterados, já que o Screener os suporta. Quando uma cláusula técnica está sob um OR, cada alternativa roda como sua própria triagem, até 6. Os resultados são mesclados, e o matched_groups de cada resultado mostra quais alternativas ele satisfez.

Higiene de resultados

Triagens ordenadas por crescimento costumavam encher com nomes minúsculos e ilíquidos mostrando números pontuais. Duas proteções agora estão ativas por padrão:

min_market_cap (₹100 Cr) é adicionada à consulta do Screener, a menos que sua consulta já tenha uma cláusula de Market Capitalization. Defina como 0 para desativar.
exclude_flagged remove linhas com números implausíveis e as lista sob excluded_for_data_quality. As verificações são: P/L abaixo de 1, salto trimestral de lucro acima de 500% em base pequena, lucro trimestral acima das vendas, vendas insignificantes, preço abaixo de ₹1 e rendimento de dividendos acima de 25% (dividendo especial ou preço desatualizado). Defina como False para manter essas linhas, marcadas com data_quality_flags.

Passe peer_relative=True para adicionar o P/L e o ROCE de cada resultado comparados com a mediana do setor.

Mantendo funcionando

O Screener.in muda suas páginas sem aviso. Uma GitHub Action agendada (canary.yml) executa scripts/canary.py todos os dias. Ela verifica as ferramentas reais contra empresas conhecidas: visões gerais, fallback autônomo, tabelas financeiras, resolução de símbolos, uma triagem técnica, comparação de setor e pares. Se uma verificação falhar, ela abre uma issue "Live canary failing". Verificações NSE apenas avisam, porque o NSE frequentemente bloqueia IPs do GitHub. Você pode executá-la localmente com python scripts/canary.py.

Envelope de resposta

Toda ferramenta retorna o mesmo formato:

{
  "status": "ok | partial | error",
  "partial": false,
  "warnings": ["MSUMI publishes no consolidated financials — showing standalone figures instead."],
  "data": { "...": "..." },
  "missing_fields": ["pe"],
  "reason": "Screener.in's page had no value for these fields.",
  "meta": { "symbol": "MSUMI", "financial_type": "standalone", "requested_symbol": "MOTHERSONWIR", "interpreted_as": "MSUMI" },
  "error": { "type": "symbol_ambiguous", "message": "...", "candidates": [{ "symbol": "TMPV", "name": "Tata Motors Passenger Vehicles Ltd" }] }
}

Campos de origem em branco aparecem em missing_fields com status: "partial", e seus valores são null, nunca "" ou 0.
Empresas sem subsidiárias têm uma página /consolidated/ em branco no Screener. O servidor recorre a números autônomos e diz isso em warnings.
Símbolos não canônicos como MOTHERSONWIR são resolvidos pela busca do Screener. Uma correspondência confiante prossegue e é registrada em meta.interpreted_as. Uma ambígua retorna error.candidates (top 3), para que você possa tentar novamente em uma chamada.
Histórico de índices implausível, como métricas baseadas em dias fora do intervalo ou um Ciclo de Conversão de Caixa que não iguala dias de devedores + estoque − fornecedores, é mantido, mas marcado como data_quality_flag: true, com um motivo.

Servidor HTTP remoto

Por padrão, isso roda via stdio — um processo local, usado por claude mcp add, Claude Desktop e clientes similares. Algumas integrações — qualquer cliente que peça uma Server URL HTTPS — precisam de um servidor de rede.

Execute com transporte HTTP:

MCP_TRANSPORT=streamable-http PORT=8000 python run_server.py
# Serves MCP over HTTP at http://<host>:8000/mcp

Variáveis de ambiente:

Variável	Propósito	Padrão
`SCREENER_USERNAME`	E-mail de login do Screener.in (necessário para ferramentas de triagem)	—
`SCREENER_PASSWORD`	Senha do Screener.in	—
`MCP_TRANSPORT`	`stdio` ou `streamable-http`	`stdio`
`PORT` / `MCP_PORT`	Porta para escutar (somente transporte HTTP)	`8000`
`MCP_HOST`	Endereço de bind (somente transporte HTTP)	`0.0.0.0`
`CHROMA_PERSIST_DIR`	Onde o armazenamento de vetores da análise de documentos é cacheado	`~/.screener-mcp/chroma_db`

Para obter uma URL HTTPS pública, implante isso em qualquer host que possa executar um processo Python de longa duração e terminar TLS para você (Render, Railway, Fly.io, uma VM atrás de um proxy reverso, etc.), e então aponte o cliente para https://your-host/mcp.

Um servidor streamable-http puro não tem autenticação. Se você o implantar publicamente, coloque-o atrás dos controles de acesso da sua plataforma (API gateway, allowlist de IP, proxy de autenticação) em vez de expô-lo à internet aberta sem autenticação — especialmente se você definir SCREENER_USERNAME/PASSWORD, já que qualquer pessoa que alcançar a URL agiria como sua conta do Screener.in.

Docker

Um Dockerfile está incluído. Ele instala todos os extras de [ai] (análise de documentos incluída) — espere um primeiro build lento (~1-2GB com torch).

# Build and tag the image
docker build -t screener-mcp:latest .

# Run it, exposing the HTTP port and setting credentials
docker run -p 8000:9000 \
  -e PORT=9000 \
  -e SCREENER_USERNAME=you@example.com \
  -e SCREENER_PASSWORD=yourpassword \
  screener-mcp:latest

Então aponte o cliente para http://<host>:8000/mcp.

Fontes de dados e limitações

Fonte	Dados fornecidos
Screener.in	Mais de 10 anos de financeiros, índices, participação acionária, pares
NSE India	Anúncios, relatórios anuais, negócios em bloco, divulgações de negociação de insiders
Yahoo Finance	Referências internacionais de commodities (COMEX, ICE Brent, NYMEX), USD/INR, alvos de consenso de analistas
Google News RSS	Manchetes recentes, incluindo menções a preços-alvo de corretoras

Dados financeiros atrasam ~1 trimestre
O Screener.in limita rajadas. O cliente espaça requisições (SCREENER_MIN_INTERVAL, padrão 0,25s) e limita concorrência (SCREENER_MAX_CONCURRENCY, padrão 3). Qualquer 429 pausa todas as requisições para um cooldown compartilhado, e as requisições são então tentadas novamente. O histórico de preços é cacheado em ~/.screener-mcp/price_cache: durante horário de mercado por 15 minutos, caso contrário até a próxima sessão. Uma triagem técnica a frio pode levar um minuto; triagens repetidas são rápidas. Defina SCREENER_PRICE_CACHE=0 para desativar o cache
Preços de commodities são as referências internacionais que os contratos MCX acompanham. O valor em INR é uma conversão cambial simples, antes de imposto de importação e GST, então fica abaixo da cotação MCX. Níquel não tem feed gratuito e retorna partial
get_company_overview retorna data.price_freshness: price_as_of, se o preço é uma impressão intradiária ou o último fechamento, o fechamento anterior e a variação do dia. Um preço mais antigo que alguns dias é sinalizado como desatualizado
Alvos de analistas vêm de duas fontes que cobrem corretoras e datas diferentes, então não vão coincidir: o consenso do Yahoo Finance e alvos extraídos de manchetes recentes. Trate qualquer um como uma visão, não a do mercado
Para bancos, NBFCs e seguradoras, verificações de dívida/patrimônio e dias de capital de giro são ignoradas porque não são significativas para credores. Avalie essas empresas por ROE, qualidade de ativos e adequação de capital
A análise de documentos requer PDFs legíveis por máquina (PDFs escaneados/somente imagem podem falhar)
Negócios em bloco da NSE capturam apenas negociações únicas > 0,5% do patrimônio
As ferramentas apoiadas pela NSE (get_company_announcements, get_insider_trading, get_bulk_deals) dependem da API pública da NSE, que frequentemente limita taxa ou bloqueia IPs de servidores. Quando isso acontece, a ferramenta retorna status: "error" com error.type: "upstream_unavailable". Quando apenas alguns dias de negócios em bloco falham, ela retorna partial. Uma lista vazia com status: "ok" significa que a NSE realmente não tinha linhas. Essas ferramentas resolvem símbolos difusos da mesma forma que as ferramentas do Screener, e retornam um erro not_on_nse para empresas listadas apenas na BSE.
Esta é uma ferramenta de pesquisa — não é aconselhamento financeiro

Estrutura do projeto

screener-mcp/
├── run_server.py
├── scripts/canary.py               # Daily live check against Screener.in (see .github/workflows/canary.yml)
├── tests/                          # Offline tests (no network) + a real-page fixture
└── src/screener_mcp/
    ├── server.py                   # FastMCP — all 30 tool definitions
    ├── client.py                   # Screener.in HTTP client + auth
    ├── core/
    │   ├── envelope.py             # Standard response envelope for every tool
    │   ├── company_page.py         # Symbol resolution + page fetch + standalone fallback
    │   ├── quality.py              # Missing-field detection + ratio sanity bounds
    │   ├── technicals.py           # Price history → 52W range, DMA, RSI, volume ratio
    │   ├── indices.py              # NSE index universes + sector benchmarks
    │   ├── yahoo.py                # Yahoo Finance session (consensus targets, estimates)
    │   ├── industry.py             # Industry pages → medians, revenue share, HHI
    │   ├── nse_client.py           # NSE India API (announcements, filings)
    │   ├── history.py              # Year-by-year series, computed ROE / debt-to-equity, CAGR
    │   ├── valuation_history.py    # Year-end P/E and P/B from Screener's chart API
    │   ├── rag.py                  # PDF → chunk → embed → query pipeline
    │   └── vector_store.py         # ChromaDB wrapper
    ├── parsers/
    │   ├── company.py              # Screener.in company page parser
    │   └── screener.py             # Screen results parser
    ├── ui/
    │   ├── stock_comparison.html   # compare_companies dashboard (MCP App)
    │   └── ext-apps-app-with-deps.js  # vendored MCP Apps runtime (MIT)
    └── tools/
        ├── company_tools.py        # Company data tools
        ├── screening_tools.py      # Stock screening + themes
        ├── technical_tools.py      # Technical screens, 52W-low candidates, sector-relative
        ├── analysis_tools.py       # Full analysis, rule-based red flags
        ├── documents.py            # Annual reports + earnings calls (RAG)
        ├── announcements.py        # NSE corporate announcements (incl. credit/ESG ratings)
        ├── shareholders.py         # NSE bulk deals (by company and/or investor)
        ├── insider_trading.py      # SEBI PIT insider trading disclosures
        ├── market_tools.py         # Recent news + analyst targets
        ├── research_tools.py       # Relative valuation, moat signals, forward outlook
        ├── commodities.py          # Commodity price analysis
        ├── notebook.py             # Research notes
        └── portfolio.py            # Local portfolio tracker

Contribuindo

Veja CONTRIBUTING.md — adicionar uma nova ferramenta leva ~10 minutos.

git clone https://github.com/LogeshR15/screener-mcp
cd screener-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

A suíte de testes é offline — sem rede, sem credenciais do Screener.in — e verifica se o registro de ferramentas e a documentação ainda concordam entre si. Se você adicionar ou renomear uma ferramenta, os testes falham até você atualizar EXPECTED_TOOLS em tests/test_tools.py, o docstring de server.py e a tabela de ferramentas do README.

Arquivos de dependência:

pyproject.toml — a fonte da verdade; o extra [ai] adiciona análise de documentos
requirements.txt — instalação completa (núcleo + análise de documentos, puxa torch)
requirements-core.txt — instalação leve, sem ferramentas de análise de documentos

Licença

Contato

Logesh Ramasamy · logeshl2003@gmail.com · LinkedIn

screener-mcp

Documentação

screener-mcp

O que você pode fazer

Início rápido

Verifique se funciona

O que ele oferece

Fluxos de trabalho de exemplo

Arquitetura

Opções de instalação

Recomendado

Claude Code

Claude Desktop

pip / PyPI

Desenvolvedor (clone local)

Avançado: HTTP e Docker

Credenciais

Ferramentas — 30 no total

Pesquisa de Empresas

Triagem de Ações

Análise de Documentos

Eventos Corporativos

Mercado e Pesquisa

Portfólio

Análise de documentos

Triagem de ações

Temas pré-construídos

Sintaxe de triagem personalizada

Cláusulas técnicas

Higiene de resultados

Mantendo funcionando

Envelope de resposta

Servidor HTTP remoto

Docker

Fontes de dados e limitações

Estrutura do projeto

Contribuindo

Licença

Contato