Canvas Student MCP

Servidor Model Context Protocol (MCP) para consultar Canvas LMS desde un asistente compatible. La ruta recomendada es local, para una sola persona, por STDIO. El proceso usa la cuenta de Canvas configurada en el archivo .env del proyecto.

Esta documentación describe el estado del repositorio auditado el 2 de octubre de 2026. El proyecto no incluye un instalador, un paquete publicado, una imagen Docker, un lockfile ni una suite de pruebas.

Índice

• Requisitos y alcance

• Instalación local

• Configurar Canvas

• Iniciar el servidor por STDIO

• Conectar un cliente MCP

• Primera comprobación segura

• Solucionar problemas

• Catálogo de herramientas

• Límites actuales y seguridad

• HTTP y despliegue remoto

• Accesibilidad e instalación futura

• Fuentes

Related MCP server: Canvas Assignment Assistant

Requisitos y alcance

• Python 3.10 o posterior, que es el mínimo requerido por la versión actual de FastMCP.

• Una cuenta de Canvas y un token personal de acceso permitido por tu institución.

• Un cliente MCP que pueda iniciar un servidor local por STDIO.

• Windows, macOS y Linux son rutas documentadas por sus comandos equivalentes; no se ha validado aquí una matriz completa de sistemas o clientes.

Las dependencias directas están en requirements.txt: FastMCP, HTTPX, python-dotenv, Pydantic, Uvicorn y Starlette. La instalación local verificada usa Python 3.14.4 y FastMCP 4.0.10 dentro de .venv.

Instalación local

Obtener el código

Con Git:

git clone https://github.com/DA0806/canvas-student-mcp.git
cd canvas-student-mcp

Si no tienes Git, descarga el ZIP desde el repositorio al que tengas acceso, extráelo y abre una terminal en la carpeta que contiene server.py. No uses una ruta personal de ejemplo del equipo de otra persona.

Crear el entorno e instalar dependencias

No hace falta activar el entorno virtual: usar el ejecutable de .venv evita que el cliente MCP dependa del PATH de la terminal.

En Windows PowerShell:

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

En macOS o Linux:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Si py -3 o python3 no existe, instala Python desde su sitio oficial y vuelve a ejecutar el comando. El servidor se ejecuta desde esta copia local; no tiene un paquete publicado para instalar con pip o uvx.

Configurar Canvas

Copia la plantilla y edita el archivo local .env:

En Windows PowerShell:

Copy-Item .env.example .env

En macOS o Linux:

cp .env.example .env

Completa únicamente estos valores:

CANVAS_BASE_URL=https://tu-institucion.instructure.com
CANVAS_API_TOKEN=pega_aqui_el_token_personal

CANVAS_BASE_URL debe ser el origen HTTPS que abre tu institución en el navegador. No agregues /courses, /api/v1 ni una ruta de un curso. Si no se define, el cliente cae en https://canvas.instructure.com; confirma siempre que el origen sea el correcto antes de usar el token.

Para un uso personal o de prueba, Canvas permite crear el token desde Cuenta → Configuración → Nuevo token de acceso. La institución puede restringir esta opción, exigir expiración o revocar el token. Cópialo solo en .env; no lo pongas en comandos, capturas, mensajes, logs ni commits. El .gitignore debe mantener .env fuera del control de versiones.

El cliente carga primero las variables del entorno y luego el bloque deployment.env de fastmcp.json si existiera. En el archivo actual no hay credenciales allí. En HTTP también puede recibir el origen mediante x-canvas-base-url/x-canvas-url y el token mediante Authorization: Bearer o x-canvas-token; esa ruta no es la recomendada para uso local compartido.

Iniciar el servidor por STDIO

Usa el comando explícito de FastMCP. Así el transporte queda fijado en STDIO y no depende del __main__ de server.py ni de que el puerto 8000 esté libre.

En Windows PowerShell, desde la raíz del repositorio:

$canvasMcpCommand = (Resolve-Path '.venv\Scripts\fastmcp.exe').Path
$canvasMcpServer = (Resolve-Path 'server.py').Path
& $canvasMcpCommand run $canvasMcpServer --transport stdio

En macOS o Linux:

.venv/bin/fastmcp run "$(pwd)/server.py" --transport stdio

El cliente puede ejecutar ese mismo comando cuando se conecte. No hace falta definir MCP_TRANSPORT si se usa --transport stdio. Como alternativa directa, el proceso acepta MCP_TRANSPORT=stdio con python server.py, pero la orden fastmcp run ... --transport stdio es la ruta principal documentada.

Conectar un cliente MCP

Codex CLI

La sintaxis local verificada es codex mcp add NOMBRE -- COMANDO ARGUMENTOS. En Windows PowerShell:

$canvasMcpCommand = (Resolve-Path '.venv\Scripts\fastmcp.exe').Path
$canvasMcpServer = (Resolve-Path 'server.py').Path
codex mcp add canvas-student -- $canvasMcpCommand run $canvasMcpServer --transport stdio

El token permanece en .env; no lo añadas como argumento de codex mcp add.

Clientes que acepten una configuración JSON STDIO

Adapta las rutas absolutas a tu equipo. Este ejemplo no incluye secretos:

{
  "mcpServers": {
    "canvas-student": {
      "command": "C:/ruta/canvas-student-mcp/.venv/Scripts/fastmcp.exe",
      "args": [
        "run",
        "C:/ruta/canvas-student-mcp/server.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

Otros clientes deben documentar explícitamente que soportan servidores locales STDIO. No se ha validado en este repositorio una integración de interfaz concreta con Claude Desktop, Cursor, Gemini, Cline, Roo Code o ChatGPT. ChatGPT requiere un transporte remoto y una configuración compatible con su producto; no asumas que puede abrir STDIO local desde una conversación de escritorio.

Primera comprobación segura

Antes de pedir datos académicos:

1. Comprueba que el cliente descubre el servidor y las 29 herramientas durante el handshake.

2. Ejecuta test_canvas_connection solo cuando hayas confirmado el origen y el token. Esta llamada sí contacta Canvas y usa la cuenta configurada.

3. Después prueba get_active_courses y verifica que el resultado corresponde a tu cuenta.

El endpoint /health, si se expone por HTTP, solo confirma que el proceso está vivo. No comprueba la URL, el token ni el acceso a Canvas. Un fallo de client.ping() tampoco es un diagnóstico válido por sí mismo: el SDK actual puede responder Method not found a ese método.

Solucionar problemas

Catálogo de herramientas

El código registra 29 herramientas MCP. Las cinco herramientas que escriben en Canvas están marcadas con Escritura Canvas y no tienen una confirmación obligatoria en el servidor; revisa cada contenido antes de invocarlas y usa las aprobaciones que ofrezca tu cliente.

Credenciales y perfil

Cursos y calificaciones

Tareas y cuestionarios

Entregas y retroalimentación

Agenda y pendientes

Anuncios y debates

Módulos, páginas y archivos

Bandeja de entrada

Límites actuales y seguridad

• La configuración está pensada para una persona por proceso. No hay autenticación propia del servidor, aislamiento multiusuario ni control de organización. configure_canvas_credentials modifica el entorno global del proceso y no debe usarse para compartir un servidor HTTP entre cuentas.

• Las cinco escrituras no tienen modo de solo lectura ni confirmación server-side. Ocultar una herramienta en la interfaz del cliente no es una barrera de seguridad.

• per_page=30/50/100 aumenta el tamaño de algunas respuestas, pero el cliente no sigue los enlaces Link de Canvas. Una lista puede quedar incompleta.

• clean_html conserva algunos encabezados, enlaces y énfasis, pero elimina etiquetas restantes y no conserva de forma completa imágenes, texto alternativo, tablas, OCR ni estructura de documentos. No sube archivos ni resuelve cuestionarios.

• format_date etiqueta la salida como UTC; no convierte la hora a la zona local y los offsets que no terminan en Z necesitan verificación en Canvas.

• La herramienta puede truncar instrucciones o resultados extensos. Confirma el contenido completo y las fechas directamente en Canvas antes de entregar un trabajo.

• Mantén el token en .env, evita pasarlo como argumento y no lo pegues en el chat. Revócalo en Canvas cuando ya no lo necesites.

HTTP y despliegue remoto

fastmcp.json declara un despliegue HTTP y server.py usa por defecto 0.0.0.0:8000 cuando se ejecuta como proceso. Eso sirve como comportamiento técnico existente, pero no convierte el proyecto en un servicio cloud listo para compartir. No hay Dockerfile, configuración de CI, lockfile ni autenticación propia.

La documentación oficial de Canvas exige OAuth para aplicaciones usadas por múltiples usuarios. Un token personal es adecuado para pruebas manuales de una cuenta, pero no para distribuir este servidor a terceros, aunque cada usuario tenga un proceso separado. Antes de proponer una instalación remota se necesitan OAuth registrado con la institución, aislamiento de sesión y cuenta, autorización de origen, TLS, límites, revocación, auditoría y redacción de secretos. Estas medidas no están implementadas en este repositorio.

Fuentes

• FastMCP: ejecutar un servidor: transporte explícito mediante CLI.

• uv: entornos virtuales: referencia opcional para trabajar con entornos, sin requerir uv en esta guía.

• Canvas: OAuth2 y autenticación: diferencia entre token personal y OAuth para aplicaciones de terceros.

• OpenAI Codex: servidores MCP: sintaxis de servidores MCP locales por STDIO.

Para el plan de mejoras de instalación y accesibilidad, consulta docs/accessibility-and-installation.md.