Install

Prerequisites

• Python 3.11+ — the server is a Python package, run via uvx.
• Your Canvas base URL — the address you normally log in at, without any path. For NUS that's https://canvas.nus.edu.sg.
• A Canvas access token — walkthrough below.

Get your Canvas access token

Canvas has no "log in with Canvas" flow for locally-installed tools, so you create a token yourself once and paste it into your AI client's config. It takes about a minute.

7~aBcDeF1234567890aBcDeF1234567890aBcDeF1234567890aBcDeF1234

One-click install

These clients support installing an MCP server from a link. Each button opens the client with canvas-api-mcp pre-filled — replace your-token-here in the client's add-server dialog with your own token from the prerequisites above before saving.

VS Code's insiders build uses the same redirect under vscode-insiders:// instead — build the link yourself from the manual VS Code config if you're on Insiders. LM Studio's deeplink requires LM Studio 0.3.17 or later.

Claude Code, Claude Desktop, Windsurf, and Zed have no install-from-link mechanism for arbitrary servers — configure them by hand in Manual configuration below.

Manual configuration

Add canvas-api-mcp to your MCP client's config, using uvx so nothing needs a separate install step. Fill in your own CANVAS_BASE_URL and the token you minted above.

claude mcp add canvas-api-mcp --scope project \
  --env CANVAS_BASE_URL=https://canvas.nus.edu.sg \
  --env CANVAS_TOKEN=your-token-here \
  -- uvx canvas-api-mcp

{
  "mcpServers": {
    "canvas-api-mcp": {
      "command": "uvx",
      "args": ["canvas-api-mcp"],
      "env": {
        "CANVAS_BASE_URL": "https://canvas.nus.edu.sg",
        "CANVAS_TOKEN": "your-token-here"
      }
    }
  }
}

Verify the connection

Restart your MCP client so it picks up the new server, then ask it to call whoami — or, if your client exposes a tool list in its UI, check that canvas-api-mcp's 18 tools appear there. A correct whoami response names the Canvas account the token belongs to and that account's role in each course. You can also ask something like "what's due this week on Canvas?" — if it calls whats_due and returns real deadlines, the token and base URL are both correct.

Troubleshooting

"Invalid token" / 401 errors. The token is wrong, expired, or was revoked. Mint a new one at Account → Settings → Approved Integrations → "+ New access token" and update your client's config with it.

It worked for weeks and then stopped. This is almost always the expiry, not a break. Student-role Canvas tokens are capped at 120 days by Instructure and often lower by the institution (NUS allows 90), so a working setup dies on a schedule you agreed to months earlier and have since forgotten. The symptom is every tool returning 401 at once, having previously been fine. Check the token's expiry date in Approved Integrations before debugging anything else: a config that has not changed did not break itself.

My institution doesn't show "Approved Integrations". Student personal-access-token generation isn't guaranteed everywhere — it varies by Canvas deployment and by institution policy. Ask your institution's IT whether student token generation is enabled; if it's disabled, this server cannot be used against that Canvas instance until it is.

Python version too old. The server requires Python 3.11+. uvx normally resolves an appropriate interpreter on its own, but if it fails, check your installed Python version and upgrade if it's below 3.11.

Server doesn't appear in the client. Confirm you fully restarted the client (for Claude Desktop, quit with Cmd+Q or the tray icon's Exit — closing the window is not enough) and that the config file is valid JSON in the exact shape shown above for your client — a missing "type": "stdio" on VS Code, a command that isn't a plain string on Zed, or a stray trailing comma anywhere will keep the server from loading. If the client logs a JSON parse error, fix the file and restart again. If it loads but calls fail, the server's own startup diagnostics name the missing or malformed environment variable.

Configuration reference

CANVAS_BASE_URL must use https:// — access tokens are password-equivalent and must not travel over plain http.

Regenerating the endpoint catalog

canvas-api-mcp ships with a bundled catalog of 1,116 Canvas API endpoints, which is what the gateway tools search_canvas_api and canvas_request search and call against. Different institutions run different Canvas versions with different endpoints enabled, so the bundled catalog is a sensible default, not a guarantee of what your own instance exposes. Most users never need to touch this.

If you want the catalog to match your institution's Canvas exactly, regenerate it from that instance's own Swagger spec:

canvas-api-mcp-build-catalog https://canvas.nus.edu.sg

This works from a plain pip/uvx install — no source checkout required. It fetches {base_url}/doc/api/api-docs.json and writes the result to ~/.cache/canvas-api-mcp/catalog.json by default. Pass -o/--output to write somewhere else instead.

canvas-api-mcp resolves which catalog to load in this order:

1. An explicit path passed in code.
2. The CANVAS_CATALOG_PATH environment variable, if set.
3. ~/.cache/canvas-api-mcp/catalog.json, if it exists.
4. The bundled catalog shipped with the package.

Regenerating with the default output path is enough on its own — the server picks it up from the cache directory on its next start, no config changes required. Set CANVAS_CATALOG_PATH (alongside CANVAS_BASE_URL and CANVAS_TOKEN in your client config) only if you want the catalog to live somewhere other than the cache directory.

Where your token goes

Your token is supplied through your MCP client's own env block and stays in that client's local config file, on your machine. It is read by the local canvas-api-mcp process and sent as a bearer token on requests made directly to your own CANVAS_BASE_URL — nowhere else. No hosted service, and no third party, ever sees it. That also means nobody else can rotate or revoke it for you: if it leaks, you're the one who deletes it from Canvas.