Servidor MCP de Canvas LMS

Un servidor de Model Context Protocol que proporciona a un cliente MCP (Claude Desktop, Claude Code o cualquier otra cosa que hable MCP) acceso de solo lectura a tu cuenta de Canvas LMS.

Responde a dos preguntas:

• "¿Qué estoy cursando y cómo me va?" — cursos activos con calificaciones actuales.

• "¿Qué me queda por entregar y cuándo vence?" — tareas pendientes con fechas de entrega.

La comunicación utiliza el transporte estándar stdio, por lo que el cliente lanza el servidor como un subproceso. Nada se escribe en stdout excepto el tráfico MCP.

Requisitos

• Node.js 18.17 o superior (el servidor usa el fetch integrado)

• Un token de acceso personal de Canvas

Related MCP server: Canvas MCP Server

Instalación

cd canvas-mcp-server
npm install

Configuración

Ambas variables son obligatorias; el servidor sale con un mensaje claro si falta alguna.

Cómo obtener un token de acceso de Canvas

1. Inicia sesión en Canvas.

2. Ve a Cuenta → Configuración.

3. En Integraciones aprobadas, haz clic en + Nuevo token de acceso.

4. Dale un propósito y (opcionalmente) una fecha de caducidad, luego haz clic en Generar token.

5. Copia el token inmediatamente — Canvas solo lo muestra una vez.

El token lleva todos tus privilegios de Canvas. Mantenlo fuera del control de versiones y revócalo desde la misma página de configuración si alguna vez se filtra.

Conectar un cliente

Añade el servidor a la configuración de tu cliente MCP, apuntando a la ruta absoluta de src/index.js:

{
  "mcpServers": {
    "canvas": {
      "command": "node",
      "args": ["/absolute/path/to/canvas-mcp-server/src/index.js"],
      "env": {
        "CANVAS_API_URL": "https://asu.instructure.com",
        "CANVAS_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

• Claude Desktop — claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).

• Claude Code — claude mcp add canvas --env CANVAS_API_URL=... --env CANVAS_ACCESS_TOKEN=... -- node /absolute/path/to/canvas-mcp-server/src/index.js

Reinicia el cliente después de editar la configuración.

Herramientas

list_courses_and_grades

Cada curso en el que estás matriculado activamente como estudiante, con su calificación actual.

Canvas informa las calificaciones dos veces cuando tu institución usa períodos de calificación: una para el período en curso y otra para todo el curso. El campo grades.scope indica cuál estás viendo:

• current_grading_period — la puntuación cubre el período de calificación en curso, y course_total_score / course_total_grade llevan los números de todo el curso.

• course_total — la institución no usa períodos de calificación, por lo que la puntuación es el total del curso.

• unavailable — Canvas no devolvió ninguna matriculación con datos de calificación.

Dentro de cualquier ámbito, current_* ignora el trabajo que aún no ha sido calificado, mientras que final_* cuenta el trabajo no calificado como un cero.

{
  "courses": [
    {
      "id": "101",
      "name": "Full Stack Web Development",
      "course_code": "GIT-411",
      "term": "Fall 2026",
      "term_start": "2026-08-20T00:00:00Z",
      "term_end": "2026-12-18T00:00:00Z",
      "enrollment_state": "active",
      "grades": {
        "current_score": 88.0,
        "current_grade": "B+",
        "final_score": 80.5,
        "final_grade": "B-",
        "scope": "current_grading_period",
        "grading_period_title": "Fall Term",
        "course_total_score": 91.4,
        "course_total_grade": "A-"
      },
      "html_url": "https://asu.instructure.com/courses/101"
    }
  ],
  "course_count": 1,
  "retrieved_at": "2026-09-01T12:00:00.000Z"
}

list_upcoming_assignments

Tareas pendientes en tus cursos activos que aún no se han entregado, ordenadas por fecha de vencimiento, primero las más próximas.

Una tarea cuenta como pendiente cuando está publicada, es calificable y no ha sido entregada, calificada o excusada. Concretamente, se filtran:

• cualquier cosa con una marca de tiempo de entrega

• entregas en estado submitted, pending_review o graded

• tareas excusadas

• tareas que ya tienen una puntuación o calificación (entrada manual o en papel)

• tareas not_graded (marcas de asistencia y similares)

• tareas no publicadas

{
  "assignments": [
    {
      "id": "9004",
      "name": "Missed lab writeup",
      "course_id": "101",
      "course_name": "Full Stack Web Development",
      "due_at": "2026-08-28T06:59:00.000Z",
      "days_until_due": -4.2,
      "overdue": true,
      "points_possible": 25,
      "submission_types": ["online_upload"],
      "submission_state": "unsubmitted",
      "missing": true,
      "locked": false,
      "unlock_at": null,
      "lock_at": null,
      "html_url": "https://asu.instructure.com/courses/101/assignments/9004"
    }
  ],
  "assignment_count": 1,
  "courses_checked": 2,
  "window": {
    "from": "2026-09-01T12:00:00.000Z",
    "to": "2026-09-15T12:00:00.000Z",
    "include_overdue": true,
    "include_undated": false
  },
  "errors": [],
  "retrieved_at": "2026-09-01T12:00:00.000Z"
}

Si un curso no se puede leer — concluido, restringido o con algún error — se lista en errors y los cursos restantes aún devuelven resultados.

Notas sobre el comportamiento

• Paginación. Canvas pagina cada colección mediante el encabezado Link. El cliente sigue rel="next" a 100 registros por página, con un máximo de 20 páginas por endpoint para que una respuesta incorrecta no pueda causar un bucle infinito.

• Concurrencia. Las tareas se obtienen de un máximo de 5 cursos a la vez para mantenerse alejado de los límites de velocidad de Canvas.

• Término actual. Por defecto, solo se devuelven los cursos cuyo término no ha terminado. El término predeterminado de Canvas no tiene fecha de finalización y siempre se incluye.

• Errores. Los fallos de Canvas se devuelven como errores de herramienta MCP que llevan el código de estado y el mensaje propio de Canvas, con una pista para los casos comunes (401 → token incorrecto, 404 → URL incorrecta).

• Solo lectura. Ambas herramientas están anotadas con readOnlyHint. El servidor solo emite solicitudes GET y nunca modifica tus datos de Canvas.

Desarrollo

npm test    # 36 tests: API client, grade logic, filtering, and an end-to-end MCP round trip

La suite usa un sustituto de fetch con cargas útiles de Canvas grabadas, por lo que no se necesita red ni token real. Todas las fechas de los fixtures son relativas al momento en que se ejecutan las pruebas.

src/
  index.js        MCP server: tool definitions, schemas, stdio wiring
  canvas.js       Canvas REST client: auth, pagination, error mapping
  courses.js      Active-course and grade normalization
  assignments.js  Outstanding-assignment filtering and due-date windows

Licencia

MIT