screener-mcp

Convierte a Claude en un analista personal de acciones indias impulsado por datos en vivo de Screener.in.

Documentación

screener-mcp

Un servidor MCP (Model Context Protocol) que le da a Claude acceso en vivo a datos de Screener.in, NSE y MCX — convirtiendo a Claude en un asistente de investigación para acciones indias.

Reportar un problema · LinkedIn · logeshl2003@gmail.com

screener-mcp conecta a Claude (Claude Code, Claude Desktop o cualquier cliente MCP) con datos de acciones indias: finanzas de empresas, selección de acciones, informes anuales, llamadas de resultados, anuncios corporativos y un rastreador de portafolio local. Señala a Claude una empresa o un filtro, y él hace la investigación usando datos reales y actuales en lugar de su conocimiento de entrenamiento sobre la acción.

Lo que puedes hacer

"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"

Inicio rápido

Requiere uv — pip install uv o brew install uv.

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

Esto instala el servidor completo, incluyendo análisis de documentos (informes anuales, llamadas de resultados). Si solo necesitas investigación de empresas y selección de acciones, omite el extra para una instalación mucho más ligera:

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

Núcleo vs. [ai]: el paquete base cubre datos de empresas, selección, anuncios de NSE y seguimiento de portafolio. El extra [ai] añade pdfplumber, chromadb y sentence-transformers (~1–2GB, vía torch) para potenciar ask_company_research y search_market_commentary (y la parte de guía de gestión de get_forward_outlook). Sin él, esas herramientas devuelven un error de "no instalado" — todo lo demás funciona normalmente.

¿Usas Claude Desktop en lugar de Claude Code? Consulta Configuración de Claude Desktop.

Verifica que funciona

claude mcp list
# screener  stdio  Connected

Luego prueba algunos prompts en Claude:

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

Si estos devuelven datos reales, el servidor está funcionando de extremo a extremo.

Lo que proporciona

Investigación de empresas — finanzas (incl. P/E, P/B, ROE e historial de deuda a capital de fin de año), tendencias de participación accionaria con evaluación de promotor/prenda, comparación entre pares, verificaciones de banderas rojas basadas en reglas (sin necesidad de inicio de sesión)
Selección de acciones — consultas personalizadas estilo Screener.in con AND / OR / paréntesis, filtros temáticos preconstruidos (los temas sectoriales parten de las empresas realmente en el sector) y cláusulas técnicas (distancia a 52 semanas, RSI, DMA, picos de volumen). Las filas basura se filtran por defecto. Los filtros fundamentales necesitan un inicio de sesión gratuito en Screener.in; los filtros solo técnicos no
Contexto de acción de precios — acciones de calidad cerca de mínimos de 52 semanas en una sola llamada, y el movimiento de una acción frente a su índice sectorial y el Nifty 50
Contexto de valoración y calidad — P/E y ROCE frente a la mediana de la industria para hasta 20 acciones a la vez, y proxies de foso: participación de ingresos, rango, concentración de la industria y qué tan duraderos han sido los retornos y márgenes
Visión prospectiva y de la calle — estimaciones de EPS/ingresos de analistas y precios objetivo, ganancias de pedidos y presentaciones de capex, guía de gestión de llamadas de resultados y noticias recientes
Análisis de documentos — haz preguntas sobre informes anuales y transcripciones de llamadas de resultados usando un pipeline RAG local
Eventos corporativos — anuncios de NSE (incl. acciones de calificación crediticia y ESG), operaciones de bloque por empresa o inversor, divulgaciones de uso de información privilegiada
Mercado e investigación — contexto de precios de materias primas, notas de investigación locales
Portafolio — un rastreador de tenencias privado y local con P&L en vivo

30 herramientas en total — referencia completa abajo. Cada herramienta devuelve el mismo sobre de respuesta, por lo que los datos parciales o degradados siempre son explícitos.

Flujos de trabajo de ejemplo

Comparar empresas — "Compare ITC and HINDUNILVR on all key ratios" → compare_companies
Buscar oportunidades — "Find low-debt, high-ROCE small caps" → screen_by_theme o screen_stocks
Encontrar retrocesos — "High-ROCE, low-debt stocks near their 52-week low" → get_52_week_low_candidates, o screen_stocks("Return on capital employed > 15 AND 52 week low distance < 10")
Mercado vs. específico de la empresa — "Is this fall sector-wide or just this stock?" → compare_to_sector
Lo que piensa la calle — "Analyst targets and recent news for TMPV" → get_analyst_targets, get_recent_news
¿Es barata para su sector? — "Which of these 15 stocks trade below their industry P/E?" → get_relative_valuation, o screen_stocks(..., peer_relative=True)
Verificación de foso — "Is MSUMI a market leader with durable returns?" → get_moat_signals
Crecimiento futuro — "What's the order pipeline and guidance for BEL?" → get_forward_outlook
Leer un informe anual — "What are the key risks in Reliance's 2024 annual report?" → ask_company_research(..., year=2024)
Leer una llamada de resultados — "What did TCS say about margins in Q3FY25?" → ask_company_research(..., quarter="Q3FY25")
A través de los años — "How has ITC described cigarette taxation over the years?" → ask_company_research(..., doc_type="annual_report")
Detectar banderas rojas — "What are the red flags in Asian Paints?" → analyze_red_flags
Seguir actividad de NSE — "Show recent announcements for HDFCBANK" → get_company_announcements
Investigar operaciones de bloque — "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")
Seguir un portafolio — "Add 10 shares of INFY at ₹1500 to my portfolio" → add_portfolio_stock
Guardar investigación — "Save a note on TITAN — strong Q3, watch margins" → notebook_ai

Arquitectura

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 obtiene y normaliza los datos; Claude hace el análisis y lo explica en lenguaje sencillo.

Opciones de instalación

Claude Code

Usa los comandos claude mcp add de arriba. Confirma con claude mcp list.

Claude Desktop

Claude Desktop no lee claude mcp add — edita su archivo de configuración directamente.

1. Instala uv si es necesario: brew install uv (o pip install uv)

2. Abre el archivo de configuración:

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

(En la aplicación: Configuración → Desarrollador → Editar configuración.)

3. Añade el servidor screener:

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

Claude Desktop no hereda el entorno de tu shell, por lo que las credenciales deben ir en el bloque "env" aquí — consulta Credenciales. Deja "env" fuera por completo si solo quieres las herramientas de investigación de empresas sin inicio de sesión.

¿spawn uvx ENOENT al iniciar? Claude Desktop arranca con un PATH mínimo. Ejecuta which uvx y usa la ruta absoluta (p. ej. /opt/homebrew/bin/uvx) como "command".

4. Cierra Claude Desktop por completo (Cmd+Q en macOS) y vuelve a abrirlo.

5. Revisa el ícono de herramientas en el compositor de mensajes — screener debería listar sus 30 herramientas. Luego pregunta: "Search for Asian Paints".

¿El servidor no aparece? Revisa Configuración → Desarrollador para ver su estado, y los registros en ~/Library/Application Support/Claude/logs/mcp-server-screener.log (macOS) o %APPDATA%\Claude\logs\ (Windows). JSON inválido — a menudo una coma final suelta — hace que Claude Desktop omita todos los servidores silenciosamente.

pip / PyPI

El paquete está publicado en PyPI como screener-mcp. uvx (arriba) lo ejecuta sin instalación persistente; para instalarlo en un entorno en su lugar:

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

Luego ejecútalo directamente, o apunta claude mcp add al punto de entrada screener-mcp que instala.

Desarrollador (clon 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

Cualquier Python 3.11+ funciona — p. ej. python3.12 -m venv .venv — solo apunta claude mcp add a ese intérprete. ¿pip install -e . falla con "el modo editable actualmente requiere una compilación basada en setuptools"? Actualiza pip en el venv primero (como arriba) y reintenta.

¿Ya lo clonaste y usas Claude Desktop? Apunta la configuración a tu intérprete del venv en lugar de uvx:

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

Avanzado: HTTP y Docker

Para despliegue remoto/de red en lugar de un proceso stdio local, consulta Servidor HTTP remoto y Docker abajo.

Credenciales

Capacidad	¿Necesita inicio de sesión en Screener.in?
Investigación de empresas (finanzas, ratios, participación accionaria, pares, banderas rojas)	No
Selección de acciones con cláusulas fundamentales (`screen_stocks`, `screen_by_theme`)	Sí
Filtros solo técnicos, `get_52_week_low_candidates`, `compare_to_sector`	No (un inicio de sesión permite que `get_52_week_low_candidates` escanee todo el mercado en lugar de un índice)
`get_relative_valuation`, `get_moat_signals`, `get_forward_outlook`, `get_analyst_targets`, `get_recent_news`	No (la guía de llamadas de resultados de `get_forward_outlook` necesita el extra `[ai]`)
Anuncios de NSE, operaciones de bloque, calificaciones crediticias, materias primas	No
Análisis de documentos, notebook, portafolio	No

Para habilitar la selección:

1. Regístrate gratis en screener.in/register

2. Claude Code / ejecuciones manuales — añade a ~/.zshrc o ~/.bashrc, luego recarga (source ~/.zshrc) y reinicia Claude Code:

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

3. Claude Desktop — no lee tu perfil de shell, por lo que los mismos dos valores deben ir en el bloque "env" de claude_desktop_config.json (consulta Configuración de Claude Desktop):

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

Nunca confirmes credenciales reales — los valores anteriores son marcadores de posición.

Herramientas — 30 en total

Agrupadas por categoría. Consulta Flujos de trabajo de ejemplo para las que usarás más a menudo.

Investigación de empresas

Herramienta	Qué hace	¿Inicio de sesión necesario?
`search_company`	Encuentra empresa por nombre o símbolo	No
`get_company_overview`	Ratios clave, precio, rango de 52 semanas, códigos NSE/BSE, información general, pros/contras de Screener	No
`get_financials`	P&L (TTM separado) / Balance general / Flujo de caja / Ratios incl. P/E, P/B, ROE, deuda a capital de fin de año	No
`get_quarterly_results`	Últimos 8 trimestres de resultados	No
`get_shareholding_pattern`	Tendencias de tenencias de 8 trimestres por categoría, detección de grupo promotor, prenda de promotor	No
`get_peer_comparison`	Tabla de comparación de pares del sector	No
`compare_companies`	2–6 acciones lado a lado, con banderas rojas puntuales; panel interactivo (aplicación MCP) donde se admita, JSON en todos lados	No
`get_full_analysis`	Todos los datos combinados para análisis profundo (mismas ventanas que las herramientas independientes)	No
`analyze_red_flags`	Verificaciones de banderas rojas basadas en reglas sobre todo el historial, cada una con evidencia y umbrales	No

Selección de acciones

Herramienta	Qué hace	¿Inicio de sesión necesario?
`screen_stocks`	Consulta de Screener.in más cláusulas técnicas (distancia a 52 semanas, RSI, DMA, pico de volumen)	Solo cláusulas fundamentales
`get_52_week_low_candidates`	Filtros de calidad + proximidad al mínimo de 52 semanas, con campos de resumen por coincidencia	No
`get_relative_valuation`	P/E y ROCE frente a la mediana de la industria para hasta 20 acciones a la vez	No
`compare_to_sector`	Retorno de la acción frente a su índice sectorial y Nifty 50, con un veredicto de mercado vs. empresa	No
`screen_by_theme`	Filtros temáticos preconstruidos — los criterios de cada tema están en la descripción de la herramienta	Solo temas de consulta

Análisis de documentos

Herramienta	Qué hace	¿Dependencias extra necesarias?
`get_document_list`	Lista informes anuales y transcripciones de llamadas de resultados	No
`ask_company_research`	Haz una pregunta sobre los informes anuales y llamadas de resultados de una empresa — todos los recientes, un `doc_type`, o un documento (`year` / `quarter` / `pdf_url`)	Sí
`search_market_commentary`	Busca una pregunta en los documentos ya indexados de múltiples empresas a la vez	Sí

ask_company_research y search_market_commentary se basan en la misma caché — el primero indexa los documentos de una empresa y los busca (uno o muchos); el segundo solo busca lo que ya está indexado en varios símbolos (bueno para "¿cuál de estas empresas mencionó Y?").

Eventos corporativos

Herramienta	Qué hace	¿Inicio de sesión necesario?
`get_company_announcements`	Anuncios corporativos de NSE con filtro de categoría — incl. `credit_rating` (CRISIL/ICRA/CARE/India Ratings) y `esg_rating`	No
`get_bulk_deals`	Operaciones de bloque de NSE por empresa (`symbol`), por inversor (`name`), o ambos	No
`get_insider_trading`	Divulgaciones de operaciones de promotores/KMP/personas designadas de SEBI PIT, sin umbral de tamaño (ambos feeds de NSE PIT combinados)	No

Mercado e investigación

Herramienta	Qué hace	¿Requiere inicio de sesión?
`get_recent_news`	Titulares de noticias recientes de una empresa (Google News), de más reciente a más antiguo	No
`get_analyst_targets`	Precio objetivo de consenso (media/mediana/máximo/mínimo, número de analistas, distribución de calificaciones) + objetivos de corredores en titulares recientes	No
`get_forward_outlook`	Estimaciones de BPA/ingresos de analistas, adjudicaciones de pedidos y presentaciones de gastos de capital, orientación de la dirección de la última llamada de resultados	No (`[ai]` para orientación)
`get_moat_signals`	Participación de ingresos/rango y concentración de la industria (HHI), además de ROCE, margen y durabilidad de la participación del promotor	No
`get_commodity_prices`	Precio de referencia internacional, movimientos del período, precio aproximado en INR + símbolos de empresas expuestas (incl. trigo; tabaco y pasta de madera solo como exposición)	No
`notebook_ai`	Guardar, leer y resumir con IA notas de investigación localmente	No

Cartera

Herramienta	Qué hace	¿Requiere inicio de sesión?
`add_portfolio_stock`	Añadir/fusionar una participación en tu cartera local (costo promedio ponderado por cantidad)	No
`update_portfolio_stock`	Sobrescribir cantidad/precio promedio en una participación existente (venta parcial, corrección de costo)	No
`remove_portfolio_stock`	Eliminar una participación por completo	No
`get_portfolio`	Ver participaciones con precio en vivo, ganancias/pérdidas (₹ y %) y peso	No

Almacenado localmente en ~/.screener-mcp/portfolio.json — sin cuenta, sin servicio externo, nada sale de tu máquina.

Análisis de documentos

El análisis de documentos (extra [ai]) utiliza un 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

Los resultados se almacenan en caché: el mismo informe no se vuelve a descargar ni procesar. Los índices creados por una versión anterior del pipeline se reconstruyen automáticamente en el siguiente uso (desde el PDF en caché). El freshness de cada documento informa last_indexed_at, el content_sha256 del PDF, su etag / last_modified, y source_changed (una verificación HEAD contra el PDF en vivo; null cuando el servidor no proporciona validadores). Si un informe fue revisado o vuelto a presentar, pasa force_reindex=True para reconstruir el índice. El manifiesto se encuentra en ~/.screener-mcp/index_manifest.json.

Cribado de acciones

Temas predefinidos

Las consultas de temas ejecutan una consulta de Screener en todo el 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

Los temas sectoriales comienzan con las empresas realmente en el sector — el lenguaje de consulta de Screener no tiene campo de industria — y luego las filtran:

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 indica de qué universo proviene (data.universe), y la descripción de screen_by_theme lleva los criterios exactos de cada tema. Tanto screen_by_theme como screen_stocks aceptan page para ir más allá de la primera página de resultados.

Sintaxis de cribado 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 admitidos: > < >= <= =, combinados con AND, OR y paréntesis

Lista completa de campos en CONTRIBUTING.md.

Cláusulas técnicas

Mezcla estas con cláusulas fundamentales usando AND, OR y paréntesis:

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)

Las cláusulas fundamentales se ejecutan en Screener.in como de costumbre. Las cláusulas técnicas se evalúan luego contra hasta max_candidates (por defecto 150) de esas coincidencias, usando el historial de precios diario de la API pública de gráficos de Screener. Una consulta con solo cláusulas técnicas escanea un índice NSE en su lugar (universe, por defecto nifty500; también nifty50, midcap100, smallcap100, smallcap250, bank, it, auto, pharma, fmcg, metal, realty, energy, defence, chemicals, ...). Si algunos candidatos no se verificaron, la respuesta tiene partial: true y un reason. El rango de 52 semanas se basa en precios de cierre.

Cuando los grupos de OR no contienen cláusulas técnicas, se envían a Screener sin cambios, ya que Screener los admite. Cuando una cláusula técnica está bajo un OR, cada alternativa se ejecuta como su propio cribado, hasta 6. Los resultados se fusionan, y el matched_groups de cada resultado muestra qué alternativas cumplió.

Higiene de resultados

Los cribados ordenados por crecimiento solían llenarse de pequeñas empresas ilíquidas que mostraban números puntuales. Dos protecciones están ahora activadas por defecto:

min_market_cap (₹100 Cr) se añade a la consulta de Screener a menos que tu consulta ya tenga una cláusula Market Capitalization. Establécelo en 0 para desactivarlo.
exclude_flagged elimina filas con números inverosímiles y las lista bajo excluded_for_data_quality. Las comprobaciones son: P/E por debajo de 1, un salto de beneficio trimestral superior al 500% sobre una base pequeña, beneficio trimestral superior a ventas, ventas insignificantes, un precio por debajo de ₹1, y un rendimiento de dividendo superior al 25% (un dividendo especial o precio obsoleto). Establécelo en False para mantener estas filas, marcadas con data_quality_flags.

Pasa peer_relative=True para añadir el P/E y ROCE de cada resultado comparado con la mediana de su industria.

Mantenerlo funcionando

Screener.in cambia sus páginas sin previo aviso. Una GitHub Action programada (canary.yml) ejecuta scripts/canary.py todos los días. Comprueba las herramientas reales contra empresas conocidas: resúmenes, el respaldo independiente, tablas financieras, resolución de símbolos, un cribado técnico, comparación sectorial y pares. Si una comprobación falla, abre un issue "Live canary failing". Las comprobaciones de NSE solo advierten, porque NSE a menudo bloquea las IPs de GitHub. Puedes ejecutarlo localmente con python scripts/canary.py.

Envoltura de respuesta

Cada herramienta devuelve la misma forma:

{
  "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 fuente en blanco aparecen en missing_fields con status: "partial", y sus valores son null, nunca "" o 0.
Empresas sin subsidiarias tienen una página /consolidated/ en blanco en Screener. El servidor recurre a cifras independientes y lo indica en warnings.
Símbolos no canónicos como MOTHERSONWIR se resuelven a través de la búsqueda de Screener. Una coincidencia segura procede y se registra en meta.interpreted_as. Una ambigua devuelve error.candidates (top 3), para que puedas reintentar en una sola llamada.
Historial de ratios inverosímil, como métricas basadas en días fuera de rango o un Ciclo de Conversión de Efectivo que no iguala días deudores + días de inventario − días de proveedores, se mantiene pero se marca data_quality_flag: true, con una razón.

Servidor HTTP remoto

Por defecto esto se ejecuta sobre stdio — un proceso local, usado por claude mcp add, Claude Desktop y clientes similares. Algunas integraciones — cualquier cliente que solicite una URL de servidor HTTPS — necesitan en su lugar un servidor de red.

Ejecútalo con transporte HTTP:

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

Variables de entorno:

Variable	Propósito	Por defecto
`SCREENER_USERNAME`	Correo de inicio de sesión de Screener.in (necesario para herramientas de cribado)	—
`SCREENER_PASSWORD`	Contraseña de Screener.in	—
`MCP_TRANSPORT`	`stdio` o `streamable-http`	`stdio`
`PORT` / `MCP_PORT`	Puerto para escuchar (solo transporte HTTP)	`8000`
`MCP_HOST`	Dirección de enlace (solo transporte HTTP)	`0.0.0.0`
`CHROMA_PERSIST_DIR`	Dónde se almacena en caché el almacén de vectores de análisis de documentos	`~/.screener-mcp/chroma_db`

Para obtener una URL HTTPS pública, despliega esto en cualquier host que pueda ejecutar un proceso Python de larga duración y terminar TLS por ti (Render, Railway, Fly.io, una VM detrás de un proxy inverso, etc.), luego apunta el cliente a https://your-host/mcp.

Un servidor streamable-http desnudo no tiene autenticación. Si lo despliegas públicamente, ponlo detrás de los controles de acceso de tu plataforma (puerta de enlace API, lista de IPs permitidas, proxy de autenticación) en lugar de exponerlo a internet abierto sin autenticación — especialmente si estableces SCREENER_USERNAME/PASSWORD, ya que cualquiera que pueda alcanzar la URL actuaría como tu cuenta de Screener.in.

Docker

Se incluye un Dockerfile. Instala todos los extras de [ai] (análisis de documentos incluido) — espera una primera compilación lenta (~1-2GB con 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

Luego apunta el cliente a http://<host>:8000/mcp.

Fuentes de datos y limitaciones

Fuente	Datos proporcionados
Screener.in	Más de 10 años de datos financieros, ratios, participación accionarial, pares
NSE India	Anuncios, informes anuales, operaciones en bloque, divulgaciones de operaciones de información privilegiada
Yahoo Finance	Referencias internacionales de materias primas (COMEX, ICE Brent, NYMEX), USD/INR, objetivos de consenso de analistas
Google News RSS	Titulares recientes, incluidas menciones de precios objetivo de corredores

Los datos financieros tienen un retraso de ~1 trimestre
Screener.in limita ráfagas de solicitudes. El cliente espacia las solicitudes (SCREENER_MIN_INTERVAL, por defecto 0.25s) y limita la concurrencia (SCREENER_MAX_CONCURRENCY, por defecto 3). Cualquier 429 pausa todas las solicitudes para un enfriamiento compartido, y las solicitudes se reintentan luego. El historial de precios se almacena en caché en ~/.screener-mcp/price_cache: durante horas de mercado durante 15 minutos, de lo contrario hasta la próxima sesión. Un cribado técnico en frío puede tomar un minuto; los cribados repetidos son rápidos. Establece SCREENER_PRICE_CACHE=0 para desactivar la caché
Los precios de materias primas son las referencias internacionales que los contratos MCX siguen. La cifra en INR es una conversión FX simple, antes del arancel de importación y GST, por lo que está por debajo de la cotización MCX. El níquel no tiene fuente gratuita y devuelve partial
get_company_overview devuelve data.price_freshness: price_as_of, si el precio es una impresión intradía o el último cierre, el cierre anterior y el cambio del día. Un precio de hace más de unos días se marca como obsoleto
Los objetivos de analistas provienen de dos fuentes que cubren diferentes corredores y fechas, por lo que no coincidirán: el consenso de Yahoo Finance y los objetivos extraídos de titulares recientes. Trata cualquiera como una vista, no como el mercado
Para bancos, NBFCs y aseguradoras, las comprobaciones de deuda a capital y días de capital de trabajo se omiten porque no son significativas para prestamistas. Evalúa estas empresas por ROE, calidad de activos y adecuación de capital
El análisis de documentos requiere PDFs legibles por máquina (los PDFs escaneados/solo imagen pueden fallar)
Las operaciones en bloque de NSE solo capturan operaciones individuales > 0.5% del capital
Las herramientas respaldadas por NSE (get_company_announcements, get_insider_trading, get_bulk_deals) dependen de la API pública de NSE, que a menudo limita la tasa o bloquea IPs de servidores. Cuando eso sucede, la herramienta devuelve status: "error" con error.type: "upstream_unavailable". Cuando solo algunos días de operaciones en bloque fallan, devuelve partial. Una lista vacía con status: "ok" significa que NSE realmente no tenía filas. Estas herramientas resuelven símbolos difusos de la misma manera que las herramientas de Screener, y devuelven un error not_on_nse para empresas listadas solo en BSE.
Esta es una herramienta de investigación — no asesoramiento financiero

Estructura del proyecto

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

Contribuir

Consulta CONTRIBUTING.md — añadir una nueva herramienta toma ~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

La suite de pruebas es offline — sin red, sin credenciales de Screener.in — y verifica que el registro de herramientas y la documentación sigan coincidiendo entre sí. Si añades o renombras una herramienta, las pruebas fallan hasta que actualices EXPECTED_TOOLS en tests/test_tools.py, el docstring de server.py, y la tabla de herramientas del README.

Archivos de dependencias:

pyproject.toml — la fuente de verdad; el extra [ai] añade análisis de documentos
requirements.txt — instalación completa (núcleo + análisis de documentos, incluye torch)
requirements-core.txt — instalación ligera, sin herramientas de análisis de documentos

Licencia

Contacto

Logesh Ramasamy · logeshl2003@gmail.com · LinkedIn

screener-mcp

Documentación

screener-mcp

Lo que puedes hacer

Inicio rápido

Verifica que funciona

Lo que proporciona

Flujos de trabajo de ejemplo

Arquitectura

Opciones de instalación

Recomendado

Claude Code

Claude Desktop

pip / PyPI

Desarrollador (clon local)

Avanzado: HTTP y Docker

Credenciales

Herramientas — 30 en total

Investigación de empresas

Selección de acciones

Análisis de documentos

Eventos corporativos

Mercado e investigación

Cartera

Análisis de documentos

Cribado de acciones

Temas predefinidos

Sintaxis de cribado personalizada

Cláusulas técnicas

Higiene de resultados

Mantenerlo funcionando

Envoltura de respuesta

Servidor HTTP remoto

Docker

Fuentes de datos y limitaciones

Estructura del proyecto

Contribuir

Licencia

Contacto