MCP-CENDOJ: Servidor MCP y API para el Buscador de Jurisprudencia
Este proyecto proporciona una API REST (FastAPI) y un Servidor MCP (Model Context Protocol) para buscar y consultar sentencias y resoluciones judiciales del CENDOJ (Centro de Documentaciรณn Judicial de Espaรฑa).
Dado que el CENDOJ no dispone de una API pรบblica y protege sus bรบsquedas con Javascript interactivo y validaciones de autocompletado, este servicio utiliza Playwright para simular bรบsquedas reales de forma automatizada y robusta, devolviendo resultados limpios en formato JSON y abstrayendo la descarga y extracciรณn de texto de los PDFs de sentencias.
Caracterรญsticas
- Buscador Automatizado (Playwright): Automatiza la navegaciรณn, la aceptaciรณn del Aviso Legal, la simulaciรณn de escritura secuencial para activar el buscador y la selecciรณn de la sugerencia del CENDOJ para evitar las limitaciones de bรบsqueda.
- API REST con FastAPI:
GET /api/status: Verifica la salud y configuraciรณn del servicio.GET /api/search: Realiza bรบsquedas avanzadas con parรกmetros:query: Texto libre opcional.fecha_desde/fecha_hasta: Rango de fechas (YYYY-MM-DD o DD/MM/AAAA).jurisdiccion: Civil, Penal, Contencioso-Administrativo, Social, Militar.roj: Identificador ROJ (ej.STS 2849/2026).ecli: Cรณdigo ECLI (ej.ES:TS:2026:2849).n_resolucion: Nรบmero de resoluciรณn.n_recurso: Nรบmero de recurso.ponente: Nombre del magistrado ponente.norma: Legislaciรณn o norma de interรฉs.localizacion: Lista de localizaciones o Comunidades Autรณnomas (ej.Andalucรญa,Cataluรฑa,Madrid).
GET /api/decision: Resuelve el contenedor de documentos del CENDOJ, descarga el archivo PDF y extrae su texto plano en espaรฑol.
- Servidor MCP (Model Context Protocol):
- Soporte para modo Stdio (para clientes locales de escritorio como Cursor y Claude Desktop).
- Soporte para modo SSE (Server-Sent Events) montado de forma nativa en FastAPI bajo el prefijo
/mcp(para clientes remotos o web). - Herramientas expuestas:
buscar_jurisprudencia: Realiza bรบsquedas con todos los filtros detallados (query, roj, ecli, ponente, recurso, resoluciรณn, norma, etc.).obtener_texto_resolucion: Descarga un PDF y extrae su texto completo.
- Compatibilidad con Windows: Parcheado para evitar problemas con la polรญtica del bucle de eventos (
NotImplementedErroren subprocess) en entornos Windows.
Requisitos Previos
- Python 3.10 o superior instalado.
- Navegador Chromium de Playwright instalado en el sistema.
Instalaciรณn y Configuraciรณn (Rรกpida)
Para facilitar la configuraciรณn en Windows, hemos incluido scripts que automatizan todo el proceso:
-
Ejecutar configuraciรณn automรกtica: Haz doble clic en el archivo
setup.bat(o ejecรบtalo desde tu consola). Este script se encargarรก de:- Crear el entorno virtual
.venv. - Instalar y actualizar todas las dependencias (
requirements.txt). - Instalar el navegador Chromium requerido por Playwright.
- Crear el archivo de configuraciรณn
.envpor defecto.
- Crear el entorno virtual
-
Registrar en Clientes MCP (Automรกtico): Una vez finalizado el setup, ejecuta la utilidad de instalaciรณn automรกtica para vincular el servidor MCP con tus clientes locales:
.venv\Scripts\python.exe install_mcp.pyEste comando detectarรก la ruta absoluta de tu repositorio y registrarรก automรกticamente el servidor CENDOJ en las configuraciones globales de:
- Claude Desktop (
claude_desktop_config.json) - Antigravity IDE (
mcp_config.json)
- Claude Desktop (
Instalaciรณn y Configuraciรณn Manual (Alternativa)
Si no deseas utilizar los scripts de automatizaciรณn, puedes inicializar el proyecto manualmente siguiendo estos pasos:
-
Crear el entorno virtual de Python:
python -m venv .venv -
Activar el entorno virtual:
- En Windows (PowerShell):
.venv\Scripts\Activate.ps1 - En macOS/Linux o Git Bash:
source .venv/bin/activate
- En Windows (PowerShell):
-
Instalar dependencias:
pip install --upgrade pip pip install -r requirements.txt -
Instalar el navegador Chromium para Playwright:
playwright install chromium -
Crear el archivo de configuraciรณn
.env: Crea un archivo llamado.enven la raรญz del proyecto y escribe la siguiente lรญnea:CENDOJ_HEADLESS=true
Guรญa de Ejecuciรณn
El script run.py es el punto de entrada unificado:
1. Ejecutar como API REST y Servidor SSE (FastAPI)
Para levantar el servidor web:
.venv\Scripts\python.exe run.py api
El servidor se iniciarรก en http://localhost:8000.
- Documentaciรณn Interactiva (Swagger/OpenAPI): Visita http://localhost:8000/docs para interactuar directamente con la API REST.
- Endpoint de MCP SSE: Accesible en http://localhost:8000/mcp/sse.
2. Ejecutar como Servidor MCP Stdio (Consola/Entrada Estรกndar)
Para iniciar el servidor MCP utilizando la entrada y salida estรกndar (ideal para integrar en herramientas de escritorio locales):
.venv\Scripts\python.exe run.py mcp
Integraciรณn Manual con Clientes MCP (Opcional)
Si prefieres realizar el registro de manera manual en lugar de usar install_mcp.py:
Claude Desktop
Para conectar este servidor MCP con Claude Desktop, edita tu archivo de configuraciรณn claude_desktop_config.json (usualmente en %APPDATA%\Claude\claude_desktop_config.json en Windows) y aรฑade la configuraciรณn del servidor:
{
"mcpServers": {
"cendoj-jurisprudencia": {
"command": "c:/workspace-github/MCP-CENDOJ/.venv/Scripts/python.exe",
"args": ["c:/workspace-github/MCP-CENDOJ/run.py", "mcp"],
"env": {
"CENDOJ_HEADLESS": "true"
}
}
}
}
Cursor
Para utilizar el servidor en Cursor:
- Ve a Settings > Features > MCP.
- Haz clic en + Add New MCP Server.
- Configura los siguientes valores:
- Name:
CENDOJ - Type:
command - Command:
c:/workspace-github/MCP-CENDOJ/.venv/Scripts/python.exe c:/workspace-github/MCP-CENDOJ/run.py mcp
- Name:
Guรญa de Prompts en Lenguaje Natural (CENDOJ MCP)
Esta guรญa muestra cรณmo puedes hablarle al asistente en lenguaje natural y conversacional (como si hablaras con un colega o un abogado), y cรณmo la IA se encarga de traducir tu peticiรณn en consultas tรฉcnicas para el buscador del CENDOJ.
๐ฌ Ejemplos Prรกcticos de Interacciรณn Conversacional
-
Consultar dudas sobre accidentes en situaciones modernas
- Tu prompt en lenguaje natural: "Oye, bรบscame casos de teletrabajadores que se hayan tropezado en su propia cocina durante el horario de trabajo y si los tribunales lo han aceptado como accidente laboral."
- Cรณmo lo procesa la IA tras bambalinas: Busca tรฉrminos como
"accidente de trabajo","teletrabajo","cocina"u"domicilio"en la jurisdicciรณn social, descarga los textos de las sentencias y analiza los hechos probados. - Respuesta que recibes: Un resumen de si los tribunales consideran la cocina como "lugar de trabajo" durante la jornada y quรฉ requisitos exigen.
-
Investigar fallos en una zona geogrรกfica especรญfica
- Tu prompt en lenguaje natural: "Necesito ver sentencias recientes de aquรญ de Valladolid sobre despidos disciplinarios a empleados que se quedaron dormidos durante su turno de vigilancia."
- Cรณmo lo procesa la IA tras bambalinas: Filtra por la sede de Valladolid (
localizacion: ["Valladolid"]), busca los tรฉrminos"despido disciplinario"y"quedarse dormido"o"vigilante"en la jurisdicciรณn social, ordenando por fecha reciente. - Respuesta que recibes: La lista de las รบltimas sentencias dictadas por el TSJ de Castilla y Leรณn en Valladolid sobre ese tema y si los despidos se declararon procedentes o improcedentes.
-
Analizar la doctrina del Tribunal Supremo sobre temas familiares
- Tu prompt en lenguaje natural: "Dime quรฉ dice el Tribunal Supremo sobre si los padres separados estรกn obligados a seguir pagando la carrera universitaria a hijos mayores de 25 aรฑos que no muestran mucho interรฉs en estudiar."
- Cรณmo lo procesa la IA tras bambalinas: Filtra por jurisdicciรณn civil y localizaciรณn Madrid (donde estรก el TS), buscando
"pensiรณn de alimentos","hijos mayores de edad","estudios","aprovechamiento". - Respuesta que recibes: Una explicaciรณn del criterio de "falta de aprovechamiento acadรฉmico" y la edad lรญmite segรบn la jurisprudencia del Tribunal Supremo.
-
Reclamaciones contra administraciones locales
- Tu prompt en lenguaje natural: "Quiero reclamar al ayuntamiento porque metรญ el pie en un socavรณn de la calzada mientras corrรญa. ยฟHay sentencias en Castilla y Leรณn donde hayan condenado al ayuntamiento por esto o suelen echarle la culpa al peatรณn?"
- Cรณmo lo procesa la IA tras bambalinas: Busca en el orden Contencioso-Administrativo de la regiรณn por
"responsabilidad patrimonial","caรญda peatรณn","socavรณn"o"bache", analizando la concurrencia de culpas. - Respuesta que recibes: Un anรกlisis de la probabilidad de รฉxito basรกndote en si los jueces locales consideran que el peatรณn debiรณ ser mรกs diligente o si la falta de mantenimiento del ayuntamiento es la causa exclusiva.
-
Resumir y explicar sentencias de gran repercusiรณn
- Tu prompt en lenguaje natural: "Tengo entendido que hay una sentencia famosa del Supremo sobre los intereses abusivos de las tarjetas revolving de Wizink. Bรบscala, lรฉela entera y explรญcame en dos pรกrrafos sencillos quรฉ decidiรณ el tribunal sobre el porcentaje de interรฉs."
- Cรณmo lo procesa la IA tras bambalinas: Localiza la sentencia clave (ej. usando palabras clave como
"Wizink","revolving","usura"), descarga su PDF completo usandoobtener_texto_resolucion, lee los fundamentos de derecho y redacta el resumen ejecutivo. - Respuesta que recibes: Una explicaciรณn sencilla libre de tecnicismos complejos sobre el umbral a partir del cual el interรฉs se considera usurario y nulo.
Pruebas y Verificaciรณn
El proyecto incluye scripts en el directorio temporal o de scratchpad para pruebas de desarrollo rรกpidas:
- Prueba de Scraper Directo:
test_scraper.pybusca un tรฉrmino e intenta descargar el primer PDF. - Prueba de API REST e Integraciรณn SSE:
test_api.pyverifica el estado, realiza una consulta y ejecuta la descarga del PDF a travรฉs del servidor FastAPI en ejecuciรณn. - Prueba de Cliente MCP Stdio:
test_mcp_stdio_client.pyinicia el servidor MCP en un subproceso y realiza las llamadas JSON-RPC oficiales simulando un cliente real.
Descargo de Responsabilidad y Tรฉrminos de Uso
[!WARNING] LEER ATENTAMENTE ANTES DE UTILIZAR LA HERRAMIENTA
Este software es una utilidad de automatizaciรณn de cรณdigo abierto provista รบnicamente con fines educativos, de investigaciรณn acadรฉmica y para consultas individuales de carรกcter privado.
1. Cumplimiento de las Normativas del CENDOJ y CGPJ
El sitio web del portal del CENDOJ (Centro de Documentaciรณn Judicial del Consejo General del Poder Judicial de Espaรฑa) establece tรฉrminos de acceso especรญficos. Al utilizar este software, el usuario asume toda la responsabilidad de cumplir con dichas polรญticas:
- Uso Particular: El acceso al buscador del CENDOJ estรก restringido รบnicamente a consultas individuales y particulares de carรกcter no mercantil.
- Prohibiciรณn de Descarga Masiva y Fines Comerciales: De acuerdo con las directrices del CGPJ, estรก terminantemente prohibido el uso de herramientas automรกticas para la extracciรณn masiva de jurisprudencia (web scraping masivo) y la explotaciรณn comercial de su base de datos. Si requieres reutilizar los datos con fines comerciales o masivos, debes solicitar una licencia de reutilizaciรณn formal directamente ante el CENDOJ.
- Frecuencia de Consultas: Se recomienda encarecidamente utilizar esta herramienta con moderaciรณn y pausas razonables para no saturar los servidores pรบblicos del CENDOJ ni infringir sus lรญmites razonables de servicio.
2. Protecciรณn de Datos Personales (RGPD / LOPDGDD)
Las sentencias publicadas por el CENDOJ han sido previamente sometidas a un proceso de anonimizaciรณn/seudonimizaciรณn. El Reglamento General de Protecciรณn de Datos (RGPD) y la Ley Orgรกnica 3/2018 (LOPDGDD) prohรญben estrictamente el uso de estas informaciones para la reidentificaciรณn de personas fรญsicas implicadas en los procedimientos judiciales. El usuario final es el รบnico responsable legal del tratamiento que dรฉ a los textos extraรญdos por este software.
3. Exenciรณn de Responsabilidad Legal
Los desarrolladores y contribuidores de este proyecto:
- No se hacen responsables del uso indebido, fraudulento o ilegal que el usuario final pueda hacer de esta API o servidor MCP.
- No asumen ninguna responsabilidad ante posibles bloqueos de direcciones IP, acciones legales, apercibimientos judiciales o cualquier medida que el CGPJ pudiera adoptar contra el usuario final como consecuencia del uso de este software.
- Proporcionan la herramienta "tal cual" (as is), sin garantรญas de ningรบn tipo respecto a su continuidad, disponibilidad tรฉcnica o exactitud de los resultados devueltos si la web del CENDOJ modifica su estructura o diseรฑo.