Skip to main content
Canvas MCP ships two entrypoints defined in pyproject.toml: the canvas CLI for interactive terminal use, and the canvas-mcp server that MCP clients connect to. This page covers both installation paths and explains when to use each one.

​
Entrypoints

The pyproject.toml scripts section declares both commands: 
[project.scripts]
canvas = "canvas_cli:main"
canvas-mcp = "mcp_entry:main"
CommandPurpose
canvasInteractive CLI — list courses, check auth, manage settings
canvas-mcpMCP server entrypoint — used by AI clients and the helper script

​
Option 1: Development checkout

Use this path when you want to modify the source code or run Canvas MCP from the repository directory.
1

Clone the repository

git clone https://github.com/ynbh/canvasmcp.git
cd canvasmcp
2

Sync dependencies

uv sync
This creates a .venv directory inside the repository and installs all runtime and dev dependencies declared in pyproject.toml.
3

Run commands with uv run

Prefix every command with uv run to use the project’s virtual environment:
uv run canvas courses
uv run canvas auth-status
uv run canvas-mcp --transport http --host 127.0.0.1 --port 8000

​
Option 2: Global tool install

Use this path when you want the canvas command available system-wide without prefixing uv run.
1

Install as a uv tool

From inside the cloned repository directory:
uv tool install .
This installs both canvas and canvas-mcp into uv’s tool bin directory and makes them available on your PATH.
2

Verify the install

canvas auth-status
No uv run prefix needed.
3

Reinstall after local changes

If you edit the source code and want those changes reflected in the global install, run:
uv tool install . --reinstall
You do not need to reinstall after changes when using the development checkout path — uv run always picks up the current source.

​
Configuring your Canvas base URL

By default, Canvas MCP infers your Canvas domain from Chrome cookies. If you have multiple Canvas domains in Chrome, or if auto-detection fails, set the CANVAS_BASE_URL environment variable: 
export CANVAS_BASE_URL=https://school.instructure.com
You can also put this in a .env file in the repository root. The scripts/start_mcp_server.sh helper passes it to the server automatically via --env-file .env.
If you have sessions for multiple Canvas institutions in Chrome and do not set CANVAS_BASE_URL, the CLI may pick the wrong domain. Set the variable explicitly in that case.

​
MCP client setup

Once installed, point your MCP client at the helper script. Use the absolute path to the script: 
{
  "mcpServers": {
    "canvasmcp": {
      "command": "/absolute/path/to/canvasmcp/scripts/start_mcp_server.sh"
    }
  }
}
The script runs uv run --env-file .env canvas-mcp with stdio transport, which is the default expected by desktop MCP clients such as Claude Desktop. For HTTP transport instead: 
uv run canvas-mcp --transport http --host 127.0.0.1 --port 8000
The MCP endpoint is then available at http://127.0.0.1:8000/mcp.
See MCP transports for a full comparison of stdio, HTTP, and SSE transport options.

Build docs developers (and LLMs) love

Get started for freeTalk to us