Bakaláři

Acesse dados do sistema escolar Bakaláři, incluindo horários, faltas e notas, por meio de uma API padronizada.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Servidor MCP Bakaláři

Servidor MCP (Model Context Protocol) para a API Bakaláři v3. Permite acesso ao sistema escolar Bakaláři por meio de uma interface MCP padronizada.

"Buy Me A Coffee" "PayPal.me"

Aviso

!! Para usar este projeto, é necessário ter um pouco de conhecimento com docker/python e saber como funciona a conexão MCP com o cliente LLM correspondente !!

Funcionalidades

  • rozvrh - Obter o horário para uma data específica ou o horário atual
  • staly_rozvrh - Obter o horário fixo (horário básico sem alterações)
  • absence - Obter informações sobre faltas
  • znamky - Obter informações sobre notas

Instalação e execução

Métodos de transporte disponíveis

O servidor suporta três métodos de transporte:

  1. CLI (stdio) - Comunicação MCP direta via stdin/stdout
  2. Proxy (HTTP) - Servidor HTTP usando mcp-proxy na porta 8805
  3. HTTP Streaming - Transporte nativo de streaming HTTP na porta 8806

Execução como servidor HTTP Streaming

Para executar com transporte nativo de streaming HTTP na porta 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

O servidor estará disponível como MCP de streaming HTTP em http://localhost:8806.

Execução como servidor HTTP usando proxy MCP

Para executar como servidor HTTP na porta 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

O servidor estará disponível como MCP SSE em http://localhost:8805.

Execução com Docker (modo stdio)

Execução rápida

# 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

Execução com 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

Execução direta com um único 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

Execução com uvx (alternativa)

Se você já tiver o pacote 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

Como funciona

Bakaláři MCP Server Logo

Compilar o pacote

Para criar um pacote de distribuição:

# Instalace build nástrojů
pip install build

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

# Výsledné soubory najdeš v dist/

Execução a partir do código-fonte

# 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 (obrigatório): Nome de usuário para Bakaláři
  • --password (obrigatório): Senha para Bakaláři
  • --url (opcional, mas recomendado): URL do servidor Bakaláři (padrão: https://skola.bakalari.cz)

Ferramentas disponíveis

rozvrh(datum)

Obtém o horário para a data especificada com informações decodificadas.

Parâmetros:

  • datum (opcional): Data no formato YYYY-MM-DD. Se não for informada, será usada a data de hoje.

Exemplo de resposta:

{
  "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()

Obtém o horário fixo (horário básico sem alterações).

Exemplo de resposta:

{
  "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
        }
      ]
    }
  ]
}

Configuração no cliente MCP (Claude Desktop / n8n)

Para o modo stdio (método original)

Para usar com Docker em vez de uvx, atualize a configuração do 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 o modo HTTP (novo método com proxy MCP)

Para usar como servidor HTTP via proxy MCP:

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

Para o modo HTTP Streaming (mais recente)

Para usar com transporte nativo de streaming HTTP:

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

GitHub Container Registry (GHCR)

Imagens Docker pré-compiladas estão disponíveis no GitHub Container Registry:

Imagens disponíveis:

  • 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 das imagens 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

Suporte multi-arquitetura:

Todas as imagens suportam:

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

Procedimentos para configuração do MCP

  1. Compile a imagem Docker:

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

  2. Execute o contêiner (para o 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. Atualize as configurações do MCP do aplicativo em claude_desktop_config.json, anythingllm_mcp_servers.json, cline_mcp_settings.json

  4. Reinicie o aplicativo para carregar a nova configuração

Autenticação

O servidor gerencia a autenticação automaticamente:

  1. No primeiro uso, faz login com nome de usuário/senha
  2. Obtém access_token e refresh_token
  3. Quando o access_token expira, renova automaticamente usando o refresh_token
  4. Se o refresh_token também expirar, faz login novamente com nome de usuário/senha

Estados de erro

Todas as ferramentas retornam mensagens de erro em caso de problemas:

{
  "error": "Popis chyby"
}

Tipos possíveis de erro:

  • Erro de autenticação: Credenciais inválidas ou problemas com token
  • Erro de API: Problema na comunicação com a API Bakaláři
  • Formato de data inválido: Data informada incorretamente

Exemplo de uso no 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")

Funcionalidades avançadas

Decodificação do horário

O servidor decodifica o horário de forma inteligente usando:

  • Tabelas de consulta: Tradução de IDs para nomes legíveis de disciplinas, professores e salas
  • Inferência de disciplinas: Reconhecimento automático da disciplina a partir do tema da aula
  • Processamento de alterações: Detecção de aulas canceladas, substituições e outras alterações
  • Validação de dados: Verificação do formato da data e validação básica

Suporte a alterações no horário

O servidor reconhece e processa corretamente:

  • Aulas canceladas: Marcadas como ❌ com preservação das informações originais
  • Substituições: Novo professor com referência ao professor original
  • Aulas combinadas: União de várias aulas em uma só
  • Alterações de salas: Local atualizado

Detalhes técnicos

  • Protocolo: MCP via stdio ou HTTP (com mcp-proxy)
  • Framework: FastMCP
  • Cliente HTTP: aiohttp (assíncrono)
  • Versão do Python: 3.8+
  • Distribuição: código-fonte
  • Proxy: mcp-proxy para transporte HTTP

Desenvolvedores

Para desenvolvimento 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

Suporte

Se esta ferramenta for útil para você, você pode apoiar o desenvolvimento:

"Buy Me A Coffee" "PayPal.me"