Bakaláři

Accede a datos del sistema escolar Bakaláři, incluyendo horarios, ausencias y calificaciones, a través de una API estandarizada.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Bakaláři

Servidor MCP (Model Context Protocol) para la API de Bakaláři v3. Permite el acceso al sistema escolar Bakaláři a través de una interfaz MCP estandarizada.

"Buy Me A Coffee" "PayPal.me"

Advertencia

!! Para usar este proyecto se necesita un poco de conocimiento de docker/python y saber cómo funciona la conexión MCP al cliente LLM correspondiente !!

Funciones

  • rozvrh - Obtener el horario para una fecha específica o el horario actual
  • staly_rozvrh - Obtener el horario fijo (horario base sin cambios)
  • absence - Obtener información sobre ausencias
  • znamky - Obtener información sobre calificaciones

Instalación y ejecución

Métodos de transporte disponibles

El servidor admite tres métodos de transporte:

  1. CLI (stdio) - Comunicación MCP directa a través de stdin/stdout
  2. Proxy (HTTP) - Servidor HTTP mediante mcp-proxy en el puerto 8805
  3. HTTP Streaming - Transporte nativo de HTTP streaming en el puerto 8806

Ejecución como servidor HTTP Streaming

Para ejecutar con transporte nativo de HTTP streaming en el puerto 8806:

# Build HTTP streaming image
./build-http.sh
# nebo manuálně
docker build -f Dockerfile.http -t mirecekd/bakalari-mcp:http .

# Spuštění
docker run -p 8806:8806 mirecekd/bakalari-mcp:http \
  --user YOUR_USERNAME \
  --password YOUR_PASSWORD \
  --url https://your-school.bakalari.cz

El servidor estará disponible como MCP de HTTP streaming en http://localhost:8806.

Ejecución como servidor HTTP mediante MCP proxy

Para ejecutar como servidor HTTP en el puerto 8805:

# Build MCP proxy image
./build-proxy.sh
# nebo manuálně
docker build -f Dockerfile.proxy -t mirecekd/bakalari-mcp:proxy .

# Spuštění s environment variables
docker run -e BAKALARI_USER=your_user -e BAKALARI_PASSWORD=your_pass -e BAKALARI_URL=your_url -p 8805:8805 mirecekd/bakalari-mcp:proxy

El servidor estará disponible como MCP SSE en http://localhost:8805.

Ejecución con Docker (modo stdio)

Inicio rápido

# Build CLI Docker image
./build-cli.sh
# nebo manuálně
docker build -f Dockerfile.cli -t mirecekd/bakalari-mcp:cli .

# Spuštění přes Docker
docker run --rm -i mirecekd/bakalari-mcp:cli \
  --user USERNAME \
  --password PASSWORD \
  --url https://your-school.bakalari.cz

Ejecución con docker-compose

# Zkopíruj a upravuješ konfiguraci
cp .env.example .env
# Edituj .env s tvými údaji

# Spuštění
docker-compose up bakalari-mcp-server

# Nebo pro development (s live reloading)
docker-compose --profile dev up bakalari-mcp-dev

Ejecución directa con un solo comando

# Pro MCP konfiguraci - nahraď uvx příkaz tímto:
docker run --rm -i ghcr.io/mirecekd/bakalari-mcp:latest-cli \
  --user YOUR_USER \
  --password YOUR_PASSWORD \
  --url https://skola.bakalari.cz

Ejecución con uvx (alternativa)

Si ya tienes el paquete compilado:

# Z místního wheel souboru
uvx --from ./dist/bakalari_mcp_server-1.0.0-py3-none-any.whl bakalari-mcp-server --user USERNAME --password PASSWORD --url https://your-school.bakalari.cz

# Nebo z aktuálního adresáře během vývoje
uvx --from . bakalari-mcp-server --user USERNAME --password PASSWORD --url https://your-school.bakalari.cz

Cómo funciona

Bakaláři MCP Server Logo

Compilar el paquete

Para crear un paquete de distribución:

# Instalace build nástrojů
pip install build

# Vytvoření balíčku
python3 -m build

# Výsledné soubory najdeš v dist/

Ejecución desde el código fuente

# Instalace závislostí
pip install fastmcp aiohttp

# Spuštění ze zdrojového kódu
python3 src/bakalari_mcp_server/server.py --user USERNAME --password PASSWORD --url https://your-school.bakalari.cz

Parámetros

  • --user (obligatorio): Nombre de usuario para Bakaláři
  • --password (obligatorio): Contraseña para Bakaláři
  • --url (opcional): URL del servidor Bakaláři (predeterminado: https://skola.bakalari.cz)

Herramientas disponibles

rozvrh(datum)

Obtiene el horario para la fecha especificada con información decodificada.

Parámetros:

  • datum (opcional): Fecha en formato YYYY-MM-DD. Si no se especifica, se usa la fecha de hoy.

Ejemplo de respuesta:

{
  "datum": "2025-05-15",
  "den_tydne": 5,
  "hodiny": [
    {
      "hodina": "1",
      "cas": "8:00 - 8:45",
      "predmet": "Matematika",
      "zkratka_predmetu": "M",
      "ucitel": "Nov",
      "mistnost": "123",
      "tema": "Kvadratické rovnice",
      "zmena": {
        "typ": "Modified",
        "popis": "Změna učitele"
      }
    }
  ],
  "pocet_hodin": 6
}

staly_rozvrh()

Obtiene el horario fijo (horario base sin cambios).

Ejemplo de respuesta:

{
  "typ": "staly_rozvrh",
  "dny": [
    {
      "den_tydne": 1,
      "den_cislo": 1,
      "hodiny": [
        {
          "hodina": "1",
          "cas": "8:00 - 8:45",
          "predmet": "Matematika",
          "zkratka_predmetu": "M",
          "ucitel": "Nov", 
          "mistnost": "123",
          "skupina": null
        }
      ]
    }
  ]
}

Configuración en el cliente MCP (Claude Desktop / n8n)

Para modo stdio (método original)

Para usar con Docker en lugar de uvx, actualiza la configuración de MCP:

{
  "mcpServers": {
    "bakalari-mcp-server": {
      "autoApprove": [
        "rozvrh",
        "staly_rozvrh"
      ],
      "disabled": false,
      "timeout": 60,
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/mirecekd/bakalari-mcp:latest-cli",
        "--user",
        "YOUR_USER",
        "--password",
        "YOUR_PASSWORD", 
        "--url",
        "https://skola.bakalari.cz"
      ],
      "transportType": "stdio"
    }
  }
}

Para modo HTTP (nuevo método con MCP proxy)

Para usar como servidor HTTP a través de MCP proxy:

{
  "mcpServers": {
    "bakalari-mcp-server": {
      "autoApprove": [
        "rozvrh",
        "staly_rozvrh"
      ],
      "disabled": false,
      "timeout": 60,
      "url": "http://localhost:8805",
      "transportType": "http"
    }
  }
}

Para modo HTTP Streaming (el más reciente)

Para usar con transporte nativo de HTTP streaming:

{
  "mcpServers": {
    "bakalari-mcp-server": {
      "autoApprove": [
        "rozvrh",
        "staly_rozvrh"
      ],
      "disabled": false,
      "timeout": 60,
      "url": "http://localhost:8806",
      "transportType": "http"
    }
  }
}

Registro de contenedores de GitHub (GHCR)

Las imágenes Docker precompiladas están disponibles en el Registro de contenedores de GitHub:

Imágenes disponibles:

  • CLI (stdio): ghcr.io/mirecekd/bakalari-mcp:latest-cli
  • Proxy (HTTP): ghcr.io/mirecekd/bakalari-mcp:latest-proxy
  • HTTP Streaming: ghcr.io/mirecekd/bakalari-mcp:latest-http

Uso de imágenes GHCR:

# CLI version
docker run --rm -i ghcr.io/mirecekd/bakalari-mcp:latest-cli \
  --user USERNAME --password PASSWORD --url https://school.bakalari.cz

# Proxy version (port 8805)
docker run -p 8805:8805 \
  -e BAKALARI_USER=USERNAME \
  -e BAKALARI_PASSWORD=PASSWORD \
  -e BAKALARI_URL=https://school.bakalari.cz \
  ghcr.io/mirecekd/bakalari-mcp:latest-proxy

# HTTP Streaming version (port 8806)
docker run -p 8806:8806 ghcr.io/mirecekd/bakalari-mcp:latest-http \
  --user USERNAME --password PASSWORD --url https://school.bakalari.cz

Soporte multi-arquitectura:

Todas las imágenes admiten:

  • linux/amd64 (Intel/AMD x64)
  • linux/arm64 (Apple Silicon, ARM64)

Procedimientos para la configuración de MCP

  1. Compila la imagen Docker:

    cd bakalari-mcp-server
# Pro stdio mode:
./build-cli.sh
# Pro HTTP mode:
./build-proxy.sh
# Nebo oba najednou:
./build-all.sh

  2. Ejecuta el contenedor (para modo HTTP):

    docker run -d -e BAKALARI_USER=your_user -e BAKALARI_PASSWORD=your_pass -e BAKALARI_URL=your_url -p 8805:8805 mirecekd/bakalari-mcp:proxy

  3. Actualiza la configuración de MCP de la aplicación en claude_desktop_config.json, anythingllm_mcp_servers.json, cline_mcp_settings.json

  4. Reinicia la aplicación para cargar la nueva configuración

Autenticación

El servidor gestiona automáticamente la autenticación:

  1. En el primer uso, inicia sesión con nombre de usuario/contraseña
  2. Obtiene access_token y refresh_token
  3. Cuando expira el access_token, lo renueva automáticamente con el refresh_token
  4. Si también expira el refresh_token, vuelve a iniciar sesión con nombre de usuario/contraseña

Estados de error

Todas las herramientas devuelven mensajes de error en caso de problemas:

{
  "error": "Popis chyby"
}

Tipos de error posibles:

  • Error de autenticación: Credenciales no válidas o problemas con el token
  • Error de API: Problema de comunicación con la API de Bakaláři
  • Formato de fecha no válido: Fecha especificada incorrectamente

Ejemplo de uso en el cliente MCP

# Získání dnešního rozvrhu
result = await mcp_client.call_tool("rozvrh")

# Získání rozvrhu pro konkrétní datum
result = await mcp_client.call_tool("rozvrh", {"datum": "2024-03-15"})

# Získání stálého rozvrhu
result = await mcp_client.call_tool("staly_rozvrh")

Funciones avanzadas

Decodificación del horario

El servidor decodifica inteligentemente el horario mediante:

  • Tablas de búsqueda: Traducción de ID a nombres legibles de materias, profesores y aulas
  • Inferencia de materias: Reconocimiento automático de la materia a partir del tema de la clase
  • Procesamiento de cambios: Detección de clases canceladas, sustituciones y otros cambios
  • Validación de datos: Verificación del formato de fecha y validación básica

Soporte de cambios en el horario

El servidor reconoce y procesa correctamente:

  • Clases canceladas: Marcadas como ❌ conservando la información original
  • Sustituciones: Nuevo profesor con referencia al original
  • Clases combinadas: Fusión de varias clases en una
  • Cambios de aula: Ubicación actualizada

Detalles técnicos

  • Protocolo: MCP a través de stdio o HTTP (con mcp-proxy)
  • Framework: FastMCP
  • Cliente HTTP: aiohttp (async)
  • Versión de Python: 3.8+
  • Distribución: código fuente
  • Proxy: mcp-proxy para transporte HTTP

Desarrolladores

Para desarrollo local:

# Klonování a setup
git clone <repository-url>
cd bakalari-mcp-server

# Instalace dev závislostí  
pip install -e .

# Spuštění pro testování
python3 src/bakalari_mcp_server/server.py --user TEST --password TEST --url https://test.bakalari.cz

Soporte

Si esta herramienta te resulta útil, puedes apoyar el desarrollo:

"Buy Me A Coffee" "PayPal.me"