ComputingVictor/MCP-BOE

MCP BOE 🇪🇸

Model Context Protocol para el Boletín Oficial del Estado español

Un servidor MCP que permite a Claude y otros LLMs acceder a la API oficial del BOE para consultar legislación consolidada, sumarios diarios y tablas auxiliares del gobierno español.

🚀 Características

• 🔍 Búsqueda de Legislación: Buscar en más de 50,000 normas consolidadas
• 📰 Sumarios del BOE: Acceder a publicaciones diarias del BOE y BORME
• 🏛️ Tablas Auxiliares: Consultar códigos de departamentos, materias y rangos normativos
• ⚡ API REST: Interfaz HTTP para usar desde cualquier aplicación
• 🤖 Compatible con MCP: Funciona con Claude Code, Ollama y otros clientes MCP
• 📊 Datos Oficiales: Conecta directamente con la API oficial del BOE

📋 Tabla de Contenidos

• Instalación
• Uso Rápido
• Configuración con Claude
• API REST
• Ejemplos
• Herramientas Disponibles
• Contribuir
• Licencia

🛠️ Instalación

Prerrequisitos

• Python 3.8 o superior
• pip (gestor de paquetes de Python)

Instalación rápida con uvx (Recomendado)

Si tienes uvx instalado, puedes usar directamente el MCP servidor sin instalación manual:

# Verificar que uvx está instalado
uvx --version

# Ejecutar directamente desde el repositorio
uvx --from git+https://github.com/ComputingVictor/MCP-BOE.git mcp-boe --help

Instalación desde el código fuente

# Clonar el repositorio
git clone https://github.com/ComputingVictor/MCP-BOE.git
cd MCP-BOE

# Instalar solo las dependencias básicas
pip install -e .

# O instalar con API REST
pip install -e ".[api]"

# O instalar todo para desarrollo
pip install -e ".[dev]"

Verificar instalación

# Prueba rápida de conectividad
python examples/basic_usage.py connectivity

# Prueba completa de funcionalidades
python examples/basic_usage.py quick

⚡ Uso Rápido

Prueba de Conectividad

# Verificar que todo funciona
python examples/basic_usage.py connectivity

Demo Interactivo

# Explorar funcionalidades de forma interactiva
python examples/basic_usage.py interactive

Ejemplos Específicos

# Buscar legislación
python examples/basic_usage.py search

# Ver sumarios del BOE
python examples/basic_usage.py summary

# Consultar departamentos
python examples/basic_usage.py departments

🔧 Configuración con Claude

Claude Code (Recomendado)

Opción 1: Con uvx (Recomendado para simplicidad)

uvx es una herramienta que simplifica enormemente la instalación y ejecución de paquetes Python. Con uvx no necesitas:

• Crear entornos virtuales manualmente
• Instalar dependencias
• Configurar variables de entorno como PYTHONPATH

uvx se encarga automáticamente de crear un entorno aislado y descargar todas las dependencias necesarias.

1. Usar uvx directamente:

{
  "mcpServers": {
    "mcp-boe": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ComputingVictor/MCP-BOE.git", "mcp-boe"],
      "transport": "stdio"
    }
  }
}

También puedes usar el archivo de configuración de ejemplo incluido:

# Descargar y usar la configuración de ejemplo
curl -O https://raw.githubusercontent.com/ComputingVictor/MCP-BOE/main/claude_mcp_config_uvx.json

2. Configurar en Claude Code:

# Usar configuración personalizada
/config-mcp /ruta/a/tu/claude_mcp_config.json

# O usar configuración de ejemplo
/config-mcp claude_mcp_config_uvx.json

Opción 2: Instalación tradicional

1. Crear archivo de configuración MCP:

{
  "mcpServers": {
    "mcp-boe": {
      "command": "/ruta/a/tu/conda/envs/tu_env/bin/python",
      "args": ["-m", "mcp_boe.server"],
      "transport": "stdio",
      "env": {
        "PYTHONPATH": "/ruta/a/tu/MCP-BOE/src"
      }
    }
  }
}

2. Configurar en Claude Code:

/config-mcp /ruta/a/tu/claude_mcp_config.json

3. Usar en Claude:

¿Puedes buscar información sobre la Ley 40/2015?
Muéstrame el sumario del BOE de esta semana
¿Qué departamentos contienen la palabra "Ministerio"?

Ollama + Open WebUI

# Instalar Open WebUI
pip install open-webui

# Configurar variables de entorno
export PYTHONPATH=/ruta/a/tu/MCP-BOE/src

# Iniciar servicios
ollama serve &
open-webui serve

🌐 API REST

Para usar desde aplicaciones web, móviles o cualquier cliente HTTP:

Iniciar el servidor API

python rest_api_wrapper.py

La API estará disponible en: http://localhost:8000 Documentación interactiva: http://localhost:8000/docs

Endpoints Disponibles

🔍 Buscar Legislación

curl -X POST "http://localhost:8000/search/legislation" \
-H "Content-Type: application/json" \
-d '{"query": "Constitución Española", "limit": 5}'

📰 Sumario del BOE

curl -X POST "http://localhost:8000/summary/boe" \
-H "Content-Type: application/json" \
-d '{"max_items": 10}'

🏛️ Buscar Departamentos

curl -X POST "http://localhost:8000/auxiliary/departments" \
-H "Content-Type: application/json" \
-d '{"search_term": "Ministerio", "limit": 10}'

🔢 Descripción de Código

curl "http://localhost:8000/auxiliary/code/7723"

💡 Ejemplos

Búsqueda de Legislación

from mcp_boe import BOEHTTPClient
from mcp_boe.tools.legislation import LegislationTools

async def buscar_ley():
    async with BOEHTTPClient() as client:
        tools = LegislationTools(client)
        
        # Buscar Ley 40/2015
        resultados = await tools.search_consolidated_legislation({
            "query": "Ley 40/2015",
            "limit": 3
        })
        
        for resultado in resultados:
            print(resultado.text)

Obtener Sumario del BOE

from mcp_boe.tools.summaries import SummaryTools
from datetime import datetime, timedelta

async def sumario_boe():
    async with BOEHTTPClient() as client:
        tools = SummaryTools(client)
        
        # Sumario de hace 3 días
        fecha = (datetime.now() - timedelta(days=3)).strftime("%Y%m%d")
        
        resultados = await tools.get_boe_summary({
            "date": fecha,
            "max_items": 5
        })
        
        for resultado in resultados:
            print(resultado.text)

Consultar Departamentos

from mcp_boe.tools.auxiliary import AuxiliaryTools

async def buscar_departamentos():
    async with BOEHTTPClient() as client:
        tools = AuxiliaryTools(client)
        
        # Buscar ministerios
        resultados = await tools.get_departments_table({
            "search_term": "Ministerio",
            "limit": 10
        })
        
        for resultado in resultados:
            print(resultado.text)

🔧 Herramientas Disponibles

📜 Legislación Consolidada

📰 Sumarios BOE/BORME

🏛️ Tablas Auxiliares

🧪 Testing

# Todas las pruebas
python examples/basic_usage.py all

# Prueba rápida
python examples/basic_usage.py quick

# Prueba específica
python examples/basic_usage.py search
python examples/basic_usage.py summary
python examples/basic_usage.py departments

🤝 Contribuir

1. Fork del proyecto
2. Crear rama para nueva funcionalidad (git checkout -b feature/nueva-funcionalidad)
3. Commit de cambios (git commit -am 'Agregar nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Crear Pull Request

Desarrollo Local

# Configurar entorno de desarrollo
python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate
pip install -e .

# Ejecutar tests
python -m pytest tests/

# Linting
python -m black src/
python -m flake8 src/

📊 Estructura del Proyecto

MCP-BOE/
├── src/mcp_boe/           # Código fuente principal
│   ├── models/            # Modelos Pydantic
│   ├── tools/            # Herramientas MCP
│   ├── utils/            # Utilidades (cliente HTTP)
│   └── server.py         # Servidor MCP principal
├── examples/             # Ejemplos de uso
├── tests/               # Pruebas unitarias
├── pyproject.toml       # Configuración del proyecto y dependencias
├── rest_api_wrapper.py  # API REST opcional
└── README.md           # Este archivo

🔒 Seguridad

• Sin autenticación requerida: La API del BOE es pública
• Rate limiting: Respeta los límites de la API oficial
• Datos oficiales: Toda la información proviene directamente del BOE
• Sin almacenamiento: No se almacenan datos localmente

📚 Documentación Adicional

• API Oficial del BOE
• Model Context Protocol
• Claude Code Documentation

🐛 Solución de Problemas

Error: "No module named 'mcp_boe'"

export PYTHONPATH="${PYTHONPATH}:/ruta/a/tu/MCP-BOE/src"

Error: "Connection refused"

Verificar conectividad con la API del BOE:

python examples/basic_usage.py connectivity

Error: Pydantic v2 warnings

Las advertencias de Pydantic v2 son normales y no afectan la funcionalidad.

📝 Changelog

v0.1.0 (2025-08-23)

• ✅ Implementación inicial del servidor MCP
• ✅ Soporte para legislación consolidada
• ✅ Sumarios del BOE y BORME
• ✅ Tablas auxiliares
• ✅ API REST wrapper
• ✅ Ejemplos y documentación

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo para más detalles.

👤 Autor

Víctor Viloria

• Email: vvictor.97@gmail.com
• GitHub: @ComputingVictor

🙏 Agradecimientos

• Al Boletín Oficial del Estado por proporcionar una API pública
• Al equipo de Anthropic por el protocolo MCP
• A la comunidad Python por las excelentes librerías

¿Tienes preguntas? Abre un issue o envía un pull request.

¿Te gusta el proyecto? ¡Dale una ⭐ en GitHub!