What it does
Librus Synergia school gradebook: grades, attendance, timetable, homework, messages.
- Connects Se ejecuta en tu computadora
- Account or key Needs LIBRUS_USERNAME, LIBRUS_PASSWORD
- Category Juegos, deportes, comida y aprendizaje
Por qué está en este puesto
Las listas se ordenan por una puntuación de uso (sobre 100) con estas partes
| Popularidad | 23/80 | Estrellas de GitHub o descargas semanales: la mayor cuenta 60, la menor 20 |
|---|---|---|
| Actualidad | 12/12 | Puntuación completa con una versión o cambio de código en 30 días |
| Sigue respondiendo | 0/8 | El endpoint en la nube respondió en la última revisión |
| Puntuación de uso | 35/100 |
Calidad: Pasó 3/3 revisiones básicas (se muestra, no ordena) · Impulso: Sin datos aún (Solo se usa en la pestaña En auge)
Instalación
Elige la app de IA que usas y copia la configuración.
Que tu IA lo instale con una frase
Instala Librus Synergia. Sigue https://mcp.popnx.com/i/krzysztofbury-librus-mcp.md, enséñame los comandos y espera mi OK antes de ejecutarlos.Pégala en una IA que trabaje en tu equipo (como Claude Code o Cursor). Lee nuestros pasos, te muestra los comandos y espera tu OK. Sin clave ni registro. · Ver el texto completo que lee tu IA
Pasó 3/3 revisiones · Funciona en tu computadora · ✓ Comandos revisados el 17 nov 2026
Primero: ¿qué IA usas?
Elige tu app y los pasos aparecen abajo.
Funciona con Claude, pero hay que preparar algo antes
Necesitas una clave de Librus Synergia (créala en el sitio del autor) · Solo en la app de Claude para computadora (Windows o Mac), no en la web ni en el móvil
Descarga el instalador del autor
Descargar el archivo .mcpb del creador
El archivo .mcpb viene directo del autor; no lo modificamos
Haz doble clic en el archivo y pulsa Install en la app de Claude de escritorio
Pruébalo
Usa Librus Synergia y dime qué puedes hacer por mí; luego muéstrame una cosa✓ Si Claude dice que está usando Librus Synergia o muestra una herramienta de Librus Synergia en la respuesta, ya está conectado
1 ajuste(s) opcional(es) (funciona sin ellos)
El comando de arriba funciona sin estos valores. Añádelos solo si quieres cambiar algo, según la descripción del autor.
LIBRUS_ALIASNombre corto para este inicio de sesión en las llamadas a herramientas.· valor por defecto librusVer original en inglés
Short name for this login in tool calls.
Descripciones traducidas automáticamente; los nombres de variables quedan como en el original. Si dudas, mira el original.
Nombres de menú comprobados con la ayuda de Anthropic el 11 nov 2026 · tu pantalla puede variar un poco según la versión
ChatGPT todavía no puede conectar Librus Synergia
Librus Synergia se instala en tu computadora, pero ChatGPT solo conecta servidores que funcionan en la web
Lo que puedes hacer en su lugar
A · Usa una app que pueda conectar Librus Synergia
- Necesitas una clave de Librus Synergia (créala en el sitio del autor) · Solo en la app de Claude para computadora (Windows o Mac), no en la web ni en el móvil
- Necesitas una clave de Librus Synergia (créala en el sitio del autor) · Instala Python (uv) en tu computadora primero (una sola vez)
- Necesitas una clave de Librus Synergia (créala en el sitio del autor) · Instala Python (uv) en tu computadora primero (una sola vez)
- Necesitas una clave de Librus Synergia (créala en el sitio del autor) · Instala Python (uv) en tu computadora primero (una sola vez)
B · Otros en Juegos, deportes, comida y aprendizaje que funcionan con ChatGPT
Elegidos entre los más usados de la misma categoría, solo los que se conectan con una dirección y sin clave
- ShipSwift✓ ChatGPT
- Anime Garden✓ ChatGPT
- Summer Engine✓ ChatGPT
Funciona con Claude Code, pero hay que preparar algo antes
Necesitas una clave de Librus Synergia (créala en el sitio del autor) · Instala Python (uv) en tu computadora primero (una sola vez)
Que la IA lo instale
Copia este mensaje en un chat de Claude Code. La IA revisa tu equipo, te dice qué archivo va a cambiar y espera tu visto bueno cada vez.
Instala el MCP server Librus Synergia para Claude Code en este equipo, en este orden: 1) Comprueba uv con uv --version. Si falta, dime que lo instale desde https://docs.astral.sh/uv/getting-started/installation/; no lo instales tú. 2) Usa solo esta configuración (ya revisada por PopNx MCP): claude mcp add --scope user librus --env LIBRUS_USERNAME=your-value --env LIBRUS_PASSWORD=your-value -- uvx librus-mcp 3) Dime la ruta completa del archivo que vas a cambiar o el comando que vas a ejecutar y espera mi visto bueno. 4) En LIBRUS_USERNAME, LIBRUS_PASSWORD deja "your-value" y dime que pegue yo el valor real en el archivo o en el campo de la app. Nunca me pidas escribir una clave en el chat. 5) Haz lo acordado y comprueba que las herramientas de Librus Synergia aparecen de verdad.Este mensaje no lleva tu clave. Si hace falta una, la IA te pedirá que la pegues tú en el archivo o en el campo de la app.
Instala uv (si no lo tienes)
¿Ya está instalado? Compruébalo primero · Abre la Terminal, escribe este comando y pulsa Enter
uv --version- Aparece un número de versión, p. ej. uv … = ya está instalado, sáltate este paso
- Aparece "command not found" (en Windows, "is not recognized") = aún no está instalado, o acabas de instalarlo y debes cerrar y volver a abrir la Terminal
Cómo abrir la Terminal
Mac: pulsa ⌘ + Espacio, escribe Terminal y pulsa Enter
Windows: abre Inicio, escribe Windows PowerShell y elige Abrir
Si no está instalado: uv no tiene instalador de clics. Copia el comando de una línea para tu sistema (macOS o Windows) desde la página oficial de uv y pégalo en la Terminal · no hace falta instalar Python aparte; uv lo descarga cuando lo necesita
Abrir la página de descarga de uv ↗
Al terminar, cierra la Terminal, ábrela de nuevo y ejecuta el mismo comando. Debe aparecer un número de versión:
uv --versionSe instala una vez y sirve para todo lo que usa uv
Regístrate y crea una clave de Librus Synergia
Abre el sitio del autor, crea una cuenta y una clave de API para el siguiente paso. Consulta precios y planes gratis en su sitio.
Cómo obtener la clave está en el README del autor, más abajo
Abre la Terminal
Mac: pulsa Command+Espacio y escribe Terminal · Windows: abre PowerShell
Pega este comando y pulsa Enter
claude mcp add --scope user librus --env LIBRUS_USERNAME=your-value --env LIBRUS_PASSWORD=your-value -- uvx librus-mcpCambia “your-value” por tu clave antes de pulsar Enter
Pega la clave solo en el campo de la app; nunca en un chat ni se la envíes a nadie
Escribe /mcp en Claude Code
Deberías ver Librus Synergia en la lista como conectado
Pruébalo
Usa Librus Synergia y dime qué puedes hacer por mí; luego muéstrame una cosa✓ Si Claude Code dice que está usando Librus Synergia o muestra una herramienta de Librus Synergia en la respuesta, ya está conectado
1 ajuste(s) opcional(es) (funciona sin ellos)
El comando de arriba funciona sin estos valores. Añádelos solo si quieres cambiar algo, según la descripción del autor.
LIBRUS_ALIASNombre corto para este inicio de sesión en las llamadas a herramientas.· valor por defecto librusVer original en inglés
Short name for this login in tool calls.
Descripciones traducidas automáticamente; los nombres de variables quedan como en el original. Si dudas, mira el original.
Nombres de menú comprobados con la ayuda de Anthropic el 11 nov 2026 · tu pantalla puede variar un poco según la versión
Funciona con Cursor, pero hay que preparar algo antes
Necesitas una clave de Librus Synergia (créala en el sitio del autor) · Instala Python (uv) en tu computadora primero (una sola vez)
Que la IA lo instale
Copia este mensaje en un chat de Cursor. La IA revisa tu equipo, te dice qué archivo va a cambiar y espera tu visto bueno cada vez.
Instala el MCP server Librus Synergia para Cursor en este equipo, en este orden: 1) Comprueba uv con uv --version. Si falta, dime que lo instale desde https://docs.astral.sh/uv/getting-started/installation/; no lo instales tú. 2) Usa solo esta configuración (ya revisada por PopNx MCP): { "mcpServers": { "librus": { "command": "uvx", "args": [ "librus-mcp" ], "env": { "LIBRUS_USERNAME": "your-value", "LIBRUS_PASSWORD": "your-value" } } } } 3) Dime la ruta completa del archivo que vas a cambiar o el comando que vas a ejecutar y espera mi visto bueno. 4) En LIBRUS_USERNAME, LIBRUS_PASSWORD deja "your-value" y dime que pegue yo el valor real en el archivo o en el campo de la app. Nunca me pidas escribir una clave en el chat. 5) Haz lo acordado y comprueba que las herramientas de Librus Synergia aparecen de verdad.Este mensaje no lleva tu clave. Si hace falta una, la IA te pedirá que la pegues tú en el archivo o en el campo de la app.
Instala uv (si no lo tienes)
¿Ya está instalado? Compruébalo primero · Abre la Terminal, escribe este comando y pulsa Enter
uv --version- Aparece un número de versión, p. ej. uv … = ya está instalado, sáltate este paso
- Aparece "command not found" (en Windows, "is not recognized") = aún no está instalado, o acabas de instalarlo y debes cerrar y volver a abrir la Terminal
Cómo abrir la Terminal
Mac: pulsa ⌘ + Espacio, escribe Terminal y pulsa Enter
Windows: abre Inicio, escribe Windows PowerShell y elige Abrir
Si no está instalado: uv no tiene instalador de clics. Copia el comando de una línea para tu sistema (macOS o Windows) desde la página oficial de uv y pégalo en la Terminal · no hace falta instalar Python aparte; uv lo descarga cuando lo necesita
Abrir la página de descarga de uv ↗
Al terminar, cierra la Terminal, ábrela de nuevo y ejecuta el mismo comando. Debe aparecer un número de versión:
uv --versionSe instala una vez y sirve para todo lo que usa uv
Regístrate y crea una clave de Librus Synergia
Abre el sitio del autor, crea una cuenta y una clave de API para el siguiente paso. Consulta precios y planes gratis en su sitio.
Cómo obtener la clave está en el README del autor, más abajo
Escribe tu clave
En la configuración de Librus Synergia, LIBRUS_USERNAME, LIBRUS_PASSWORD está vacío; añade tu clave y guarda
Pega la clave solo en el campo de la app; nunca en un chat ni se la envíes a nadie
Abre el chat de IA de Cursor en modo Agent
Pruébalo
Usa Librus Synergia y dime qué puedes hacer por mí; luego muéstrame una cosa✓ Si Cursor dice que está usando Librus Synergia o muestra una herramienta de Librus Synergia en la respuesta, ya está conectado
1 ajuste(s) opcional(es) (funciona sin ellos)
El comando de arriba funciona sin estos valores. Añádelos solo si quieres cambiar algo, según la descripción del autor.
LIBRUS_ALIASNombre corto para este inicio de sesión en las llamadas a herramientas.· valor por defecto librusVer original en inglés
Short name for this login in tool calls.
Descripciones traducidas automáticamente; los nombres de variables quedan como en el original. Si dudas, mira el original.
Nombres de menú comprobados con la ayuda de Cursor el 11 nov 2026 · tu pantalla puede variar un poco según la versión
Funciona con VS Code, pero hay que preparar algo antes
Necesitas una clave de Librus Synergia (créala en el sitio del autor) · Instala Python (uv) en tu computadora primero (una sola vez)
Que la IA lo instale
Copia este mensaje en un chat de VS Code. La IA revisa tu equipo, te dice qué archivo va a cambiar y espera tu visto bueno cada vez.
Instala el MCP server Librus Synergia para VS Code en este equipo, en este orden: 1) Comprueba uv con uv --version. Si falta, dime que lo instale desde https://docs.astral.sh/uv/getting-started/installation/; no lo instales tú. 2) Usa solo esta configuración (ya revisada por PopNx MCP): { "servers": { "librus": { "type": "stdio", "command": "uvx", "args": [ "librus-mcp" ], "env": { "LIBRUS_USERNAME": "your-value", "LIBRUS_PASSWORD": "your-value" } } } } 3) Dime la ruta completa del archivo que vas a cambiar o el comando que vas a ejecutar y espera mi visto bueno. 4) En LIBRUS_USERNAME, LIBRUS_PASSWORD deja "your-value" y dime que pegue yo el valor real en el archivo o en el campo de la app. Nunca me pidas escribir una clave en el chat. 5) Haz lo acordado y comprueba que las herramientas de Librus Synergia aparecen de verdad.Este mensaje no lleva tu clave. Si hace falta una, la IA te pedirá que la pegues tú en el archivo o en el campo de la app.
Instala uv (si no lo tienes)
¿Ya está instalado? Compruébalo primero · Abre la Terminal, escribe este comando y pulsa Enter
uv --version- Aparece un número de versión, p. ej. uv … = ya está instalado, sáltate este paso
- Aparece "command not found" (en Windows, "is not recognized") = aún no está instalado, o acabas de instalarlo y debes cerrar y volver a abrir la Terminal
Cómo abrir la Terminal
Mac: pulsa ⌘ + Espacio, escribe Terminal y pulsa Enter
Windows: abre Inicio, escribe Windows PowerShell y elige Abrir
Si no está instalado: uv no tiene instalador de clics. Copia el comando de una línea para tu sistema (macOS o Windows) desde la página oficial de uv y pégalo en la Terminal · no hace falta instalar Python aparte; uv lo descarga cuando lo necesita
Abrir la página de descarga de uv ↗
Al terminar, cierra la Terminal, ábrela de nuevo y ejecuta el mismo comando. Debe aparecer un número de versión:
uv --versionSe instala una vez y sirve para todo lo que usa uv
Regístrate y crea una clave de Librus Synergia
Abre el sitio del autor, crea una cuenta y una clave de API para el siguiente paso. Consulta precios y planes gratis en su sitio.
Cómo obtener la clave está en el README del autor, más abajo
Escribe tu clave
En la configuración de Librus Synergia, LIBRUS_USERNAME, LIBRUS_PASSWORD está vacío; añade tu clave y guarda
Pega la clave solo en el campo de la app; nunca en un chat ni se la envíes a nadie
Abre el chat de IA de VS Code en modo Agent
Pruébalo
Usa Librus Synergia y dime qué puedes hacer por mí; luego muéstrame una cosa✓ Si VS Code dice que está usando Librus Synergia o muestra una herramienta de Librus Synergia en la respuesta, ya está conectado
1 ajuste(s) opcional(es) (funciona sin ellos)
El comando de arriba funciona sin estos valores. Añádelos solo si quieres cambiar algo, según la descripción del autor.
LIBRUS_ALIASNombre corto para este inicio de sesión en las llamadas a herramientas.· valor por defecto librusVer original en inglés
Short name for this login in tool calls.
Descripciones traducidas automáticamente; los nombres de variables quedan como en el original. Si dudas, mira el original.
Nombres de menú comprobados con la ayuda de VS Code el 11 nov 2026 · tu pantalla puede variar un poco según la versión
Otras apps que usan MCP, como Windsurf, Zed o Gemini CLI, añaden servidores de forma distinta. Míralo en la lista de apps
Ver todas las apps que usan MCP →
La configuración JSON está en “Para desarrolladores”, abajo
Para desarrolladores: comandos de Terminal y configuración JSON
Instalado en tu computadora
Claude Code
claude mcp add --scope user librus --env LIBRUS_USERNAME=your-value --env LIBRUS_PASSWORD=your-value -- uvx librus-mcpClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"librus": {
"command": "uvx",
"args": [
"librus-mcp"
],
"env": {
"LIBRUS_USERNAME": "your-value",
"LIBRUS_PASSWORD": "your-value"
}
}
}
}Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"librus": {
"command": "uvx",
"args": [
"librus-mcp"
],
"env": {
"LIBRUS_USERNAME": "your-value",
"LIBRUS_PASSWORD": "your-value"
}
}
}
}VS Code (mcp.json)
{
"servers": {
"librus": {
"type": "stdio",
"command": "uvx",
"args": [
"librus-mcp"
],
"env": {
"LIBRUS_USERNAME": "your-value",
"LIBRUS_PASSWORD": "your-value"
}
}
}
}Valores que debes completar
LIBRUS_USERNAMEsecreto obligatorio envLibrus Synergia login.LIBRUS_PASSWORDsecreto obligatorio envLibrus Synergia password.LIBRUS_ALIASenvNombre corto para este inicio de sesión en las llamadas a herramientas.Ver original en inglés
Short name for this login in tool calls.
Descripciones traducidas automáticamente; los nombres de variables quedan como en el original. Si dudas, mira el original.
Esta configuración se genera a partir de la ficha del creador en el registro. Si el README dice otra cosa, sigue el README.
De un vistazo
- Descargas por semanai
- 589/sem
- Conexión
- Se ejecuta en tu computadora
- Última versióni
- 2.9.0
- Publicado en el registroi
- 17 nov 2026
- Último cambio de códigoi
- 17 nov 2026
- Creador
- krzysztofbury
- Paquetes
pypi: librus-mcpoci: ghcr.io/krzysztofbury/librus-mcp:2.9.0mcpb: …/librus-mcp-2.9.0.mcpb- Estado en el registro
- Activo
Qué apps pueden usarlo
Según cómo se conecta este servidor y la documentación de cada app, comprobado el 10 nov 2026.
Se ejecutan en tu computadora en
ClaudeGooseLM StudioMsty StudioCherry StudioCursorVS Code + GitHub CopilotVisual StudioWindsurf (Devin Desktop)ZedKiroClineContinueJetBrains AI AssistantClaude CodeCodex CLIGemini CLIOpenCodenodecodeWarpLibreChatRaycast
Qué puede hacer
Se ejecuta en tu computadora; la lista de herramientas aparece en tu app de IA después de instalarlo.
Revisiones básicasi
Revisamos información que cualquiera puede ver; no hemos leído el código. Las revisiones que no aplican no se cuentan. · Revisado el 19 nov 2026
- ✓ Superada
El creador coincide con el repo
El nombre en el registro se verificó con la cuenta de GitHub krzysztofbury, dueña del repo
- ✓ Superada
Sigue en mantenimiento
Último cambio de código: anteayer
- ✓ Superada
Tiene licencia
Usa MIT
- – No aplica
El endpoint responde
Este se ejecuta en tu computadora; no hay endpoint en internet
- – No aplica
Inicio de sesión con OAuth
Se ejecuta en tu computadora y usa ajustes locales en su lugar
- … Aún sin revisar
Sin instrucciones ocultas en las descripciones de herramientas
Se ejecuta en tu computadora; solo podemos leer listas de herramientas de endpoints en internet
Vulnerabilidades publicadas (OSV.dev)
Aún no revisado
Creadores: pedir otra revisión o avisar de un dato erróneo
Para autores: añade una insignia a tu README
Si lo creaste tú, pega este código en tu README. La insignia enlaza a esta página.
[](https://mcp.popnx.com/en/servers/krzysztofbury-librus-mcp)Conversación
Pregunta, comparte un consejo o avisa de que no funciona. Ordenado por lo que la gente marcó como útil.
Aún no hay publicaciones. Sé la primera persona en preguntar o compartir.
Lo publicado aquí lo escriben usuarios, no el equipo de PopNx.
Reseñas de usuarios
Aún no hay reseñas
Comparado con otros en Juegos, deportes, comida y aprendizajei
- Más estrellas que el 97% de los otros 1619 servidores de esta categoría
- Publicado en el registro más recientemente que el 92% de los otros 1619 servidores de esta categoría
- Revisiones básicas iguales o mejores que el 99% de los otros 1619 servidores de esta categoría
Comparado con todos los servidores activos de esta categoría en el registro. Las estrellas solo cuentan cuando quien lo publica es dueño del repo.
Preguntas frecuentes
¿Es seguro Librus Synergia?
Superó 3 de 3 revisiones básicas aplicables. No hemos leído el código. Antes de agregar una clave o un token, revisa qué acceso pide el servidor y usa una clave que tenga solo los permisos que necesitas.
¿Qué claves o códigos necesita?
Debes completar: LIBRUS_USERNAME, LIBRUS_PASSWORD
¿Se ejecuta en mi computadora o en la nube?
Se ejecuta en tu computadora. Tu app de IA lo inicia cuando hace falta, y los datos no pasan por los servidores del creador (a menos que el propio servidor llame a un servicio en línea).
¿Sigue en mantenimiento?
El repo de GitHub cambió por última vez anteayer, y la última versión (2.9.0) llegó al registro anteayer.
¿Qué apps pueden usarlo?
Las apps compatibles con MCP, como Claude Desktop, Claude Code, Cursor y VS Code. También necesitas Python (uv), Docker, MCPB en tu computadora.
¿Qué puedo usar en su lugar?
En la misma categoría: Anime Garden, WilmAI, Lumify Sports Intelligence, Savecraft, GoodWatch
Alternativas parecidas
Misma categoría, otros creadores, comandos ya revisados. Primero los oficiales, luego por estrellas.
Cómo leer una tarjeta:↓ Descargas por semanai★ Estrellas de GitHubiTres pilares: reseñas · revisiones · usoiActualizado = fecha en que se publicó la última versión en el registroi
WilmAI
Finland's Wilma school system for parents and students: schedule, homework, exams and messages.
Lumify Sports Intelligence
Schedules, scores, odds, splits & explainable AI bet confidence — 8+ sports, free instant key.
Savecraft
Savecraft serves real save game data and expert game knowledge to AI assistants.
GoodWatch
Find movies and TV shows, track watches, and get suggestions based on your taste.
| Este Librus Synergia | Anime Garden | WilmAI | Lumify Sports Intelligence | Savecraft | GoodWatch | |
|---|---|---|---|---|---|---|
| Dónde se ejecuta | Se instala en tu equipo | Funciona en la nube, sin instalar nada | Se instala en tu equipo | Funciona en la nube, sin instalar nada | Funciona en la nube, sin instalar nada | Funciona en la nube, sin instalar nada |
| Necesita clave | Sí | No | No | Sí | No | No |
| Se añade con + en Claude | No | No | No | No | No | No |
| Revisiones básicas | 3/3 | 4/4 | 3/3 | 4/4 | 3/4 | 4/4 |
| Licencia | MIT | AGPL-3.0 | MIT | MIT | Apache-2.0 | MIT |
| Precio | Sin coste en el registro | Sin coste en el registro | Sin coste en el registro | Sin coste en el registro | Sin coste en el registro | Sin coste en el registro |
README del creador
Abrir el README
Copiado tal cual del repo del creador. PopNx MCP no lo ha revisado ni lo respalda. Se quitaron HTML, imágenes y scripts. Los enlaces llevan fuera de este sitio.
Librus MCP Server
An MCP server that gives AI assistants access to the Librus Synergia school gradebook: grades, attendance, timetable, homework, calendar, announcements, messages, formative assessments, school-year history, class-free days and student information. It supports several logins at once, built on the independent librus-python-api.
Version 2.0 replaces the librus-apix backend used by every earlier version. Upgrading from 1.x? See Upgrading from 1.x.
Quick start
The commands below pin 2.8.1, using the native API 1.10.1. You need your Librus Synergia login and password. Accounts that require interactive two-factor authentication are not supported.
Pick one way to run it:
| Way | Best for | Credentials |
|---|---|---|
| On your computer | Claude Code, Claude Desktop, Gemini CLI, Codex, OpenCode, Hermes on the same machine | a private config.json, any number of logins |
| Desktop bundle | one-click install in apps that support MCP Bundles | the app's settings form, one login |
| Self-hosted with Docker | agents on another machine of yours, connecting over HTTP | a private config.json or environment, any number of logins |
| MCP Registry | clients that install servers from the official registry | the client's settings form, one login |
All of them run the server on a machine you control. It connects only to Librus; see Privacy.
On your computer
You do not need to clone this repository or install Python yourself. uv downloads Python 3.14 and the server automatically.
1. Install uv. On macOS or Linux, open a terminal and run:
curl -LsSf https://astral.sh/uv/install.sh | sh
On Windows, open PowerShell and run:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Close and reopen your AI assistant afterwards.
2. Create a private configuration file. Save this as config.json in a private folder under your user account, outside projects and synchronized folders, and fill in the login and password:
{
"accounts": [ {"alias": "daughter", "username": "12345", "password": "YOUR_PASSWORD"} ] }
The alias is the short name you use when asking about this login. For more logins, add more objects to accounts, each with its own alias:
{
"accounts": [ {"alias": "anna", "username": "12345", "password": "FIRST_PASSWORD"}, {"alias": "jan", "username": "67890", "password": "SECOND_PASSWORD"} ] }
Suggested locations:
- macOS:
/Users/YOUR_NAME/.config/librus-mcp/config.json - Linux:
/home/YOUR_NAME/.config/librus-mcp/config.json - Windows:
C:\Users\YOUR_NAME\.config\librus-mcp\config.json
On first start the server restricts the file to your user (macOS/Linux), creates its private state directory (~/.librus-mcp) and a persistent key there. There is nothing else to set up. Notifications and attachment downloads are on by default; sending messages is off; opening a received message marks it read without asking. To change that, add for example:
"features": {"notifications": true, "attachments": false, "send_message": true, "mark_read_consent": true}
For a single login you can skip the file and set environment variables instead: LIBRUS_USERNAME, LIBRUS_PASSWORD and optionally LIBRUS_ALIAS (default librus). Installers that collect settings in a form use these.
3. Connect your assistant. Replace the path with your file's absolute path.
Claude Code:
claude mcp add --scope user --transport stdio librus \
-- uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.json
Claude Desktop (Settings > Developer > Edit Config):
{
"mcpServers": { "librus": { "command": "uvx", "args": ["--python", "3.14", "librus-mcp==2.8.1", "--config", "/absolute/path/to/config.json"] } } }
Gemini CLI:
gemini mcp add --scope user --transport stdio \
librus uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.json
OpenAI Codex CLI:
codex mcp add librus \
-- uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.json
OpenCode:
opencode mcp add librus --global -- \
uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.json
Hermes Agent (~/.hermes/config.yaml):
mcp_servers:
librus: command: "uvx" args: ["--python", "3.14", "librus-mcp==2.8.1", "--config", "/absolute/path/to/config.json"]
Check the setup without contacting Librus:
uvx --python 3.14 librus-mcp==2.8.1 --config /absolute/path/to/config.json --check-config
If a GUI assistant cannot find uvx, use its absolute path (which uvx or where uvx). Restart or reconnect the assistant after changing the file.
Desktop bundle (preview)
Each release attaches librus-mcp-2.8.1.mcpb to its GitHub release. Open it with an app that supports MCP Bundles, such as Claude Desktop. The app asks for the Librus login and password, keeps them in its settings, and installs Python 3.14 and the exact dependency versions this release was tested with. The bundle serves one login; use On your computer for several.
Self-hosted with Docker
Run the server on your own Docker host and connect agents on other machines over HTTP. Every request needs a bearer token. The server has no TLS of its own, so expose it only through a reverse proxy with TLS or a private network such as Tailscale or WireGuard. Never publish the port on a public or shared network.
1. Prepare a private folder on the Docker host with the configuration and a token. The files must belong to the user that runs the container and be readable only by it:
mkdir -p ~/librus-mcp/data && cd ~/librus-mcp
config.json: the same format as above, any number of logins
docker run --rm ghcr.io/krzysztofbury/librus-mcp:2.8.1 --generate-token > token chmod 600 config.json token
2. Start it with this compose.yaml, replacing 1000:1000 with the output of id -u and id -g:
services:
librus-mcp: image: ghcr.io/krzysztofbury/librus-mcp:2.8.1 command: ["--transport", "http", "--allowed-host", "librus-mcp.example.lan:*"] user: "1000:1000" environment: LIBRUS_CONFIG: /config/config.json LIBRUS_MCP_TOKEN_FILE: /config/token volumes:
- ./config.json:/config/config.json:ro
- ./token:/config/token:ro
- ./data:/data ports:
Loopback for a reverse proxy on this host, or your VPN address instead.
- "127.0.0.1:8000:8000" restart: unless-stopped
docker compose up -d
docker compose logs librus-mcp
The endpoint is /mcp at your proxy's HTTPS address, or at your VPN address on port 8000. --allowed-host lists the host names clients use; NAME:* accepts NAME with any port or none. A reverse proxy must forward the original Host header: Caddy and Traefik do by default, nginx needs proxy_set_header Host $host;. Without --allowed-host the server logs that Host header checks are off and relies on the token alone. In the image the server listens on every container interface; the ports: line decides who can reach it. ./data keeps the private state, persistent key and downloads, so back it up.
3. Connect your agent with the token as a bearer header. For Hermes Agent:
mcp_servers:
librus: url: "https://librus-mcp.example.lan/mcp" headers: Authorization: "Bearer YOUR_TOKEN"
Other clients that support streamable HTTP take the same URL and header.
Things to know about HTTP mode:
- One token grants every configured login. Run one deployment per trusted person, and replace the token if it leaks.
- Let one agent poll notifications for each login: delivery and acknowledgement are designed for a single consumer.
download_attachmentsaves files on the Docker host under./data/downloads. A remote agent cannot read that path; small files (up to 256 KiB) are also offered as a short-lived MCP resource.- If you enable
send_message, anyone with the token can confirm a send preview. The server warns about this at startup. - Without a
user:line the container runs as uid 10001; a named volume then works as is, but the configuration and token files must belong to uid 10001. - Instead of files,
LIBRUS_ACCOUNTS(a JSON list of accounts), orLIBRUS_USERNAMEandLIBRUS_PASSWORDfor one login, andLIBRUS_MCP_TOKENcan be passed as environment variables.
The same image also runs over stdio for a client on the Docker host: docker run -i --rm -v librus-mcp-data:/data -e LIBRUS_USERNAME -e LIBRUS_PASSWORD ghcr.io/krzysztofbury/librus-mcp:2.8.1.
MCP Registry
The server is listed in the official MCP Registry as io.github.krzysztofbury/librus-mcp, with the PyPI package, the container image and the desktop bundle. Clients that install from the registry ask for LIBRUS_USERNAME and LIBRUS_PASSWORD, and optionally LIBRUS_ALIAS.
Upgrading from 1.x
Change the version in your assistant's configuration to librus-mcp==2.8.1, add --python 3.14 before it and keep your existing --config file. On first start 2.0 adapts the old setup automatically: it creates the key, restricts shared 1.x folders to your user, ignores the removed behaviour-notes setting and adopts 1.x notification history on the first check. Stop 1.x server processes that use the same folders before switching, and copy the state folder first: going back to 1.x is not supported other than by restoring that copy (see the migration guide).
Notifications and attachments stay on by default, as in 1.x. Tool names and results changed on purpose (for example list_students is now list_accounts and student_alias is account_alias). Assistants read the new tool list automatically; custom scripts must follow the migration guide.
Tools and safety
The default catalog has 32 typed tools:
- Accounts/profile:
list_accounts,get_student_information. - Grades:
get_grades,get_final_grades,get_grades_window. - Attendance:
get_attendance,get_attendance_window,get_attendance_detail,get_attendance_frequency,get_subject_frequency. - School:
get_timetable,get_announcements,get_agenda,get_agenda_detail,get_homework,get_homework_detail,get_completed_lessons,get_school_year_archive,get_class_free_days,get_justifications(parent logins). - Communication:
get_messages,get_message_content,get_recipient_types,get_recipient_choices,get_recipients,get_message_correspondents,get_teacher_subjects,get_message_unread_counts. - Notifications:
get_new_notifications,get_notification_status,acknowledge_notifications(featurenotifications). - Files:
download_attachmentand runtime-only attachment resources (featureattachments).
Enabling the send_message feature adds preview_message, send_message, get_send_outcome and get_send_history, for 36 tools. Disabling notifications and attachments leaves 28 tools.
Collections are paged with limit and a cursor; an announcements page also ends early when long texts would exceed the result size cap (reason: "size_limit"). Every login is independent, including logins for the same student. Modern messaging is the default; set `"me