Bakaláři

You can access Bakaláři school data through a dedicated MCP server that exposes the school system via standardized MCP endpoints. It supports retrieving schedules, constant schedules, absences, and grades, and can be driven from both local (stdio) clients and HTTP-based MCP transports.

How to use

You connect to the MCP server using an MCP client configured for either stdio (local) mode or an HTTP transport. Choose the transport that fits your setup. The server provides tools to fetch your class timetable, the base timetable, attendance information, and grades. When you configure your client, you’ll enable tools such as rozvrh (schedule) and staly_rozvrh (permanent schedule) to retrieve data for the current day or a specific date.

To start, select one of the available connection methods. The HTTP streaming transport runs a native HTTP MCP server on port 8806. The HTTP proxy transport runs an HTTP MCP server on port 8805. The stdio transport runs locally via a process you start and communicate with over stdin/stdout.

How to install

Prerequisites you should have in place before starting: Docker or uvx (Python-based tool for running Python wheels), Python 3.8 or newer, and access to a Bakaláři server URL with a valid user and password.

Choose one of the following installation paths and run the exact commands below.

# Build HTTP streaming image
./build-http.sh
# or manually
docker build -f Dockerfile.http -t mirecekd/bakalari-mcp:http .

# Run HTTP streaming server (port 8806)
docker run -p 8806:8806 mirecekd/bakalari-mcp:http \
  --user YOUR_USERNAME \
  --password YOUR_PASSWORD \
  --url https://your-school.bakalari.cz

# Build MCP proxy image for HTTP transport
./build-proxy.sh
# or manually
docker build -f Dockerfile.proxy -t mirecekd/bakalari-mcp:proxy .

# Run HTTP proxy server (port 8805)
docker run -e BAKALARI_USER=your_user -e BAKALARI_PASSWORD=your_pass -e BAKALARI_URL=your_url -p 8805:8805 mirecekd/bakalari-mcp:proxy

# Run via CLI in stdio mode using Docker (inline example)
docker run --rm -i mirecekd/bakalari-mcp:cli \
  --user USERNAME \
  --password PASSWORD \
  --url https://your-school.bakalari.cz

# Run with GHCR CLI image
# (same pattern as above but using the GHCR image)
docker run --rm -i ghcr.io/mirecekd/bakalari-mcp:latest-cli \
  --user YOUR_USER \
  --password PASSWORD \
  --url https://school.bakalari.cz

# Run using uvx from a local wheel (stdio mode)
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

# Start from source code (development mode)
pip install fastmcp aiohttp
python3 src/bakalari_mcp_server/server.py --user USERNAME --password PASSWORD --url https://your-school.bakalari.cz

# Quick single-command stdio run (alternative CLI approach)
docker run --rm -i ghcr.io/mirecekd/bakalari-mcp:latest-cli \
  --user YOUR_USER \
  --password YOUR_PASSWORD \
  --url https://skola.bakalari.cz

# Optional: use uvx in development (from current directory)
uvx --from . bakalari-mcp-server --user USERNAME --password PASSWORD --url https://your-school.bakalari.cz

Configuration and usage tips

Configure your MCP client with explicit server entries for each transport you plan to use. The HTTP entries point to the proxy or streaming endpoints, while the stdio entries point to the local commands that run inside containers or local processes. Include any authentication tokens or environment variables as shown in the inline examples.

Security, authentication and errors

The server manages authentication automatically. You first provide a username and password, receive an access token and a refresh token, and the system renews the access token when needed. If the refresh token expires, you will re-authenticate with your username and password. Typical error types include authentication failures, API communication problems, and invalid date formats.

Troubleshooting and notes

If you encounter errors, check the error payloads returned by tools. A typical error looks like {"error": "Popis chyby"}. Ensure that your Bakaláři URL is reachable and that the provided credentials are correct. When using HTTP transports, verify that the port mappings (8805 for proxy, 8806 for streaming) are accessible from your client network.

Examples of common tasks

Fetch today’s schedule or a schedule for a specific date using the corresponding MCP tool rozvrh. Retrieve the static base timetable with staly_rozvrh to compare against daily changes.

Notes on available transports and ports

HTTP Streaming: http://localhost:8806. HTTP Proxy: http://localhost:8805. STDIO mode executes locally and communicates over stdin/stdout.

Developer and maintenance information

The server uses FastMCP as its underlying framework with an async HTTP client (aiohttp). It runs on Python 3.8+ and is distributed as source code. For HTTP transport, the mcp-proxy is used to provide the HTTP interface.

Available tools

rozvrh

Fetches the schedule for a given date or the current day, with decoded details.

staly_rozvrh

Fetches the fixed base schedule without changes.

absence

Retrieves absence information from Bakaláři.

znamky

Retrieves information about grades.