FilingsMCP 📈

Convierte las presentaciones oficiales de BSE (Bombay Stock Exchange) en Markdown limpio y listo para IA para Claude y Cursor.

Si introduces un PDF financiero en un LLM, normalmente falla: las tablas se desmoronan, las páginas escaneadas quedan en blanco y el modelo gasta tokens en basura de diseño. FilingsMCP corrige la entrada. Obtiene las presentaciones directamente de BSE, convierte los PDF basados en texto en Markdown estructurado y los expone a través de un servidor del Model Context Protocol (MCP) para que tu IA pueda leerlos, buscarlos y analizarlos de forma nativa.

✨ Características principales

• Conversión a Markdown listo para IA: Transforma diseños de PDF complejos en Markdown limpio y estructurado. Elimina encabezados y pies de página repetidos, corrige el mojibake (texto corrupto de fuentes de subconjunto) y marca explícitamente los PDF de imágenes escaneadas para que tu IA nunca alucine por el ruido del diseño.

• Frontmatter de procedencia enriquecido: Cada archivo .md generado incluye frontmatter YAML (headline, date, category, source_pdf, news_id, extraction_status), lo que proporciona a la IA un contexto estricto y fuentes citables.

• Datos históricos profundos: Se nutre tanto del feed de anuncios de BSE como del archivo de informes anuales, obteniendo presentaciones que se remontan a 1997 (incluidas las de empresas excluidas de cotización).

• Biblioteca estructurada e indexada: Los archivos se organizan sistemáticamente: <TICKER>/<category>/<YYYY>/<file>.pdf junto a su archivo hermano .md. Genera automáticamente archivos INDEX.md por empresa y maestros para una navegación sencilla.

• Deduplicación inteligente y escrituras atómicas: Combina fuentes superpuestas sin descargar duplicados. Escribe archivos de forma atómica, lo que significa que una descarga interrumpida nunca deja un archivo a medio escribir o corrupto en tu biblioteca.

• MCP listo para la nube: Se despliega en Render (o cualquier nube) en segundos mediante SSE, lo que permite que múltiples clientes de IA consulten una única biblioteca alojada.

Related MCP server: sec-edgar-mcp

🚀 Casos de uso listos para usar

Como los datos están estructurados limpiamente con frontmatter e índices categorizados, tu agente de IA puede realizar análisis profundos y multidocumento de inmediato:

1. Síntesis de llamadas de resultados (Concall) de varios años

Prompt: "Lee las transcripciones de concall de los últimos 3 años de TANLA. ¿Ha sido precisa la guía de la dirección sobre los márgenes de EBITDA? Cita las fechas y citas específicas."

• Cómo funciona: La IA usa search_filings para obtener los archivos .md de concall, lee el texto limpio y contrasta las guías entre años sin alucinar números.

2. Análisis del foso y del modelo de negocio

Prompt: "Analiza los informes anuales de Reliance Industries de 2015 a 2023. Identifica los cambios en su combinación de ingresos (Retail vs Jio vs O2C) y resume el foso central."

• Cómo funciona: La IA extrae la categoría annual-reports, lee el markdown estructurado y extrae los datos tabulares de ingresos que normalmente destruiría el análisis estándar de PDF.

3. Informes automatizados de diligencia debida

Prompt: "Obtén los últimos 5 años de resultados financieros y presentaciones para inversores de Escorts Kubota. Redacta un informe HTML con citas sobre su economía unitaria y la trayectoria del segmento de tractores."

• Cómo funciona: La IA obtiene las presentaciones exactas mediante las herramientas MCP, lee el frontmatter de procedencia para asegurarse de que está viendo los años correctos y genera un informe con citas que enlazan con los PDF de origen.

4. Seguimiento de acciones del consejo y dividendos

Prompt: "Enumera todas las declaraciones de dividendos y los resultados de las reuniones del consejo de TITAN en los últimos 2 años."

• Cómo funciona: La IA filtra por las categorías corp-actions y board-meetings, extrayendo las fechas de registro exactas y los importes de pago del Markdown limpio.

🏗️ Cómo funciona

1. Obtener y resolver: Le dices a la IA que descargue una empresa (p. ej., «Descarga TANLA»). El servidor MCP resuelve el código de valor contra la API en vivo de BSE.

2. Descargar y convertir: El motor descarga los PDF, extrae el texto, limpia la basura y escribe atómicamente los archivos hermanos .pdf y .md en el disco.

3. Indexar: Se generan un INDEX.md maestro y un INDEX.md por empresa.

4. Consultar: Tu agente de IA usa las herramientas MCP (search_filings, read_filing) para navegar por la biblioteca de Markdown limpio.

☁️ Despliegue (Render)

Este proyecto incluye un Blueprint render.yaml para el despliegue en la nube con un solo clic. Un servidor MCP alojado te permite consultar tu biblioteca desde cualquier lugar sin ejecutar un servidor Python local.

1. Sube este repositorio a GitHub.

2. Ve a Render y haz clic en New + → Blueprint.

3. Selecciona tu repositorio. Render detectará automáticamente el render.yaml.

4. Haz clic en Apply.

5. Render aprovisionará un servicio web y adjuntará un disco persistente de 10GB (en /data) para que tus presentaciones descargadas sobrevivan a los reinicios.

Una vez desplegado, Render proporcionará una URL (p. ej., https://filings-mcp-xyz.onrender.com).

🔌 Conexión con Claude Desktop / Cursor

Una vez que tu servidor esté en funcionamiento (localmente o en Render), añádelo a la configuración de tu cliente MCP.

Para la nube (Render SSE):

{
  "mcpServers": {
    "filings-mcp": {
      "url": "https://your-render-url.onrender.com/sse"
    }
  }
}

Para Stdio local:

{
  "mcpServers": {
    "filings-mcp": {
      "command": "filings-mcp",
      "args": ["--root", "~/FilingsLibrary"]
    }
  }
}

🛠️ Herramientas MCP disponibles

Cuando está conectado, tu agente de IA tiene acceso a las siguientes herramientas:

💻 Desarrollo local

Si prefieres ejecutar el motor localmente:

# Clone the repo
git clone https://github.com/sathanandhh/filingsmcp.git
cd filingsmcp

# Set up Python 3.11+
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

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

# Run the MCP server (defaults to ~/FilingsLibrary)
filings-mcp --root ./MyLibrary

📄 Licencia

Licencia MIT. Creado para la investigación financiera impulsada por IA.