Canvas LMS 数据查询 MCP 服务器

Canvas MCP Server

A Model Context Protocol (MCP) server that lets AI assistants (Cursor, Claude Desktop, and any other MCP client) query your Canvas LMS data — courses, terms, and more — through the Canvas GraphQL API.

Features

• Query Canvas via GraphQL (single request, no REST pagination juggling)
• Typed responses validated with Pydantic models
• Structured error reporting (auth failures, rate limits, missing resources)
• Runs over stdio — works with any MCP client
• Graceful shutdown on SIGINT/SIGTERM

Available Tools

Course, assignment, submission, grade, and announcement data comes from the Canvas GraphQL API; todo items, upcoming assignments, dashboard (active_only) course lists, planner, calendar events, discussions, quizzes, rubrics, unified course search, modules, syllabi, pages, and files/folders use the REST API where GraphQL does not expose them (or where REST is the accurate source of truth).

Requirements

• Python 3.13+
• uv (recommended) or pip
• A Canvas API access token

Installation

git clone https://github.com/sarthakneupane/canvas-mcp-server.git
cd canvas-mcp-server
uv sync            # creates .venv and installs everything from uv.lock

Or with pip:

pip install -e .

Configuration

1. Copy the example environment file:

   复制

   cp .env.example .env
   

2. Edit .env:

   复制

   CANVAS_API_TOKEN=your_actual_api_token_here
   CANVAS_BASE_URL=https://your-school.instructure.com/api
   

   • Token: generate one in Canvas under Account → Profile → Approved Integrations → "New Access Token". Treat it like a password.

   • Base URL: must end at /api (not /api/v1) — the server posts GraphQL queries to {CANVAS_BASE_URL}/graphql. Use your own institution's Canvas domain: it is the URL you see in the browser when you log in to Canvas, with /api appended. Most schools use https://<your-school>.instructure.com, while some use a custom domain such as https://canvas.<your-school>.edu — use whichever one you log in with. The public Free-for-Teacher instance (canvas.instructure.com) was permanently discontinued in 2026, so an institution domain is required.

   • Downloads: files are saved under CANVAS_DOWNLOAD_DIR (default ~/Downloads/Canvas), organized as {course_name}/{optional_folder}/{filename}. Tools accept only a relative folder name — never an absolute path. Download tools save Canvas Files only (binary uploads). They do not export wiki Pages, assignment HTML, or other module item types — use get_page, get_assignment_details, or get_assignment_resources to read that content in the chat instead. Downloads stream to disk (not fully buffered in memory), enforce CANVAS_MAX_DOWNLOAD_SIZE_MB, validate that file URLs match your CANVAS_BASE_URL host, and suffix duplicate filenames (e.g. notes (1).pdf).

Tool errors

On failure, every tool returns a structured error object instead of raising. Agents should branch on code and retryable; error is a legacy alias of title.

Common codes: canvas_unauthorized (401), canvas_forbidden (403), resource_not_found (404), canvas_rate_limited (429, retryable), canvas_unavailable (5xx, retryable), invalid_argument (bad tool input), discussion_locked (require_initial_post), download_failed.

Full catalog and agent guidance: docs/errors.md.

Output conventions

List tools return a ListResult object (results, result_count, truncated) instead of a bare array. Each list tool accepts limit (default 50, max 100). GraphQL-backed models use camelCase; REST-backed models use snake_case. Timestamps serialize as ISO-8601; nullable fields serialize as JSON null.

Details: docs/output-conventions.md.

Security & privacy

Canvas HTML is converted to plain text and never executed in this server. Content tools attach provenance metadata (source_type, course_id, resource_id, canvas_url) so agents can treat bodies as untrusted. API tokens are redacted from error strings and URLs where possible.

Student-scoped tokens only receive the authenticated user's grades and submissions; classmate roster leaks from Canvas are filtered out.

Details: SECURITY.md. Privacy regression tests: uv run pytest -m privacy.

Usage

Standalone

uv run canvas-mcp-server

The server communicates over stdio (stdin/stdout JSON-RPC); it is meant to be launched by an MCP client rather than used interactively.

With Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project), using the absolute path to your clone:

{
  "mcpServers": {
    "canvas": {
      "command": "/absolute/path/to/canvas-mcp-server/.venv/bin/canvas-mcp-server"
    }
  }
}

Then refresh MCP servers in Cursor Settings and ask e.g. "list my Fall 2025 courses".

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "canvas": {
      "command": "/absolute/path/to/canvas-mcp-server/.venv/bin/canvas-mcp-server"
    }
  }
}

Development

uv sync --extra dev               # install runtime + dev deps (pytest, respx, …)
uv run python scripts/run_server.py   # run the dev server

uv run pytest                    # run tests (mocked Canvas — no live token needed)
uv run black src/ tests/         # formatting
uv run isort src/ tests/
uv run mypy src/ --strict        # type checking

Tests use mocked Canvas responses (tests/fixtures/, tests/helpers/canvas_mock.py). No CANVAS_API_TOKEN or .env file is required — CI and local runs use empty credentials:

CANVAS_API_TOKEN= CANVAS_BASE_URL= uv run pytest

Project Structure

canvas-mcp-server/
├── src/canvas_mcp_server/
│   ├── server.py          # FastMCP server setup, tool registration, entry point
│   ├── config.py          # Environment configuration (.env)
│   ├── tools/             # MCP tools (one file per tool)
│   ├── models/            # Pydantic models for Canvas responses
│   ├── errors/            # Structured error codes and mappers
│   ├── constants/         # Canvas enums (workflow states, enrollment types, ...)
│   └── utils/             # HTTP + Canvas client, HTML, downloads, pagination
├── docs/                  # Architecture, tools, errors, API notes
├── .github/workflows/     # CI (pytest, black, isort, mypy)
├── scripts/               # Development scripts
└── tests/                 # Test suite (mocked Canvas)

Contributing

See CONTRIBUTING.md for setup, architecture overview, and the new-tool checklist. Key docs:

Quick start: fork → branch → uv run pytest + uv run mypy src/ --strict → PR.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Author

Sarthak Neupane

• GitHub: @Sarthak-Neupane