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 — Pesquisa de Ações Indianas para Claude

Transforme o Claude em um analista pessoal de ações indianas alimentado por dados ao vivo do Screener.in — agora com análise de documentos por IA, anúncios da NSE e cadernos de pesquisa.

Mais de 300 usuários ativos · Reportar um problema · LinkedIn · logeshl2003@gmail.com

O que você pode perguntar

"Compare ITC and HUL on all key ratios"
"Find chemical stocks with low debt and strong growth"
"Explain Jyothy Labs like I'm a beginner"
"What are the red flags in Asian Paints?"
"Find hidden gems below ₹5000 crore market cap"
"What did TCS management say about margins in Q3FY25?"
"Summarize the key risks from Reliance's 2024 annual report"
"Show me recent dividend announcements for HDFCBANK"
"How does copper price affect Havells and Polycab?"
"Save a research note on TITAN — strong Q3, watch margins"

Instalação rápida

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

Requer uv: pip install uv ou brew install uv

Instalação manual:

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

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

Configuração de credenciais

Os dados financeiros das empresas funcionam sem login. A triagem de ações requer uma conta gratuita.

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

2. Adicione a ~/.zshrc ou ~/.bashrc:

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

3. Recarregue o shell (source ~/.zshrc) e reinicie o Claude Code.

Para análise de documentos (relatórios anuais, teleconferências de resultados), instale dependências extras:

pip install pdfplumber sentence-transformers chromadb
# or: pip install -e ".[ai]"

Verifique a conexão

claude mcp list
# screener  stdio  Connected

Então pergunte ao Claude: "Search for Asian Paints" — você deve obter resultados.

Ferramentas — 21 no total

Pesquisa de Empresas

Ferramenta	O que faz	Requer login
`search_company`	Encontre empresa por nome ou símbolo	Não
`get_company_overview`	Principais indicadores, preço, faixa de 52 semanas, sobre	Não
`get_financials`	DRE / Balanço Patrimonial / Fluxo de Caixa / Indicadores	Não
`get_quarterly_results`	Últimos 8 trimestres de resultados	Não
`get_shareholding_pattern`	Tendência de participação de Promotores / FII / DII	Não
`get_peer_comparison`	Tabela de comparação com pares do setor	Não
`compare_companies`	Comparação lado a lado (2–5 ações)	Não
`compare_stocks_ui`	Painel interativo (Claude Desktop)	Não
`get_full_analysis`	Todos os dados combinados para análise aprofundada	Não
`analyze_red_flags`	Detecção estruturada de sinais de alerta	Não
`explain_for_beginners`	Explicação da empresa em linguagem simples	Não

Triagem de Ações

Ferramenta	O que faz	Requer login
`screen_stocks`	Consulta personalizada no Screener.in	Sim
`screen_by_theme`	Telas temáticas pré-construídas	Sim
`list_investment_themes`	Mostrar todos os temas disponíveis	Não

Análise de Documentos (novo)

Ferramenta	O que faz	Dependências extras necessárias
`get_document_list`	Listar relatórios anuais e transcrições de teleconferências de resultados	Não
`analyze_annual_report`	Faça qualquer pergunta sobre PDFs de relatórios anuais	Sim
`analyze_earnings_call`	Faça qualquer pergunta sobre transcrições de teleconferências de resultados	Sim

Usa um pipeline RAG local: PDF → pdfplumber → ChromaDB → sentence-transformers. Os resultados são armazenados em cache no disco — o mesmo relatório nunca é baixado ou reindexado novamente.

Eventos Corporativos (novo)

Ferramenta	O que faz	Requer login
`get_company_announcements`	Anúncios corporativos da NSE com filtro de categoria	Não
`search_shareholder`	Encontre atividade de investidores via negociações em bloco da NSE	Não

Mercado e Pesquisa (novo)

Ferramenta	O que faz	Requer login
`get_commodity_prices`	Contexto de preços de commodities + empresas impactadas	Não
`notebook_ai`	Salve, leia e resuma com IA notas de pesquisa localmente	Não

Temas de triagem pré-construídos

undervalued_small_cap       Small caps, ROCE > 15%, low debt, PE < 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 Improving profits, compressed valuation
improving_roce              ROCE > 15% with profit momentum
hidden_gems                 Small cap, high ROCE, strong growth
dividend_aristocrats        Consistent dividends with quality financials
qarp                        Quality at reasonable price
micro_cap_growth            High-growth micro caps < ₹1000 Cr
ev_theme                    EV & auto ancillary growth companies
chemicals                   Specialty chemicals, strong fundamentals
defense                     Defense sector with revenue momentum
railways                    Railway infra/equipment companies
renewable_energy            Renewable energy sector

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: > < = AND

Lista completa de campos em CONTRIBUTING.md.

Como funciona a análise de documentos

analyze_annual_report("TCS", 2024, "What are the key risks?")

  1. Fetch PDF link from Screener.in / NSE
  2. Download and parse with pdfplumber
  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 returns top-5 relevant excerpts
  7. Claude reasons over the excerpts to answer your question

Results are cached — the same report is never re-processed twice.

Arquitetura

screener-mcp/
├── run_server.py
└── src/screener_mcp/
    ├── server.py                   # FastMCP — all 21 tool definitions
    ├── client.py                   # Screener.in HTTP client + auth
    ├── core/
    │   ├── nse_client.py           # NSE India API (announcements, filings)
    │   ├── 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
    └── tools/
        ├── company_tools.py        # Company data tools
        ├── screening_tools.py      # Stock screening + themes
        ├── analysis_tools.py       # Deep analysis, red flags, beginner
        ├── documents.py            # Annual reports + earnings calls (RAG)
        ├── announcements.py        # NSE corporate announcements
        ├── shareholders.py         # Bulk deal / shareholder search
        ├── commodities.py          # Commodity price analysis
        └── notebook.py             # Research notes

Fontes de dados e limitações

Fonte	Dados fornecidos
Screener.in	Mais de 10 anos de dados financeiros, indicadores, participação acionária, pares
NSE India	Anúncios, relatórios anuais, negociações em bloco
MCX India	Preços de commodities (melhor esforço)

Os dados financeiros têm defasagem de ~1 trimestre
A análise de documentos requer PDFs legíveis por máquina (PDFs escaneados/somente imagem podem falhar)
As negociações em bloco da NSE capturam apenas negociações individuais > 0,5% do capital
Esta é uma ferramenta de pesquisa — não é aconselhamento financeiro

Contribuição

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

Contato

Logesh Ramasamy · logeshl2003@gmail.com · LinkedIn