io.github.Fireiscoolsolo/canvas-lms-mcp-local

[!TIP] Want it on your phone, on the web, or across several computers? Go to the 🌐 Remote Edition →. It has the same 209 tools, served over a password-protected ngrok tunnel with automatic failover between computers.

💻 Canvas LMS MCP: Local Edition

Use Canvas from your AI assistant on your own computer. No tunnel, no passwords, no background service.

209 tools · One config file · Nothing exposed to the internet

Website · Quick start · Configuration · Tools · Troubleshooting

🤔 Local or Remote?

✨ Highlights

• 📊 Grade intelligence: what_if_grade, compute_needed_score, grade_impact_ranking, full weighted breakdowns
• 📅 Planning: get_week_ahead, semester_snapshot, study_priority_ranking, cross-course missing work in one call
• 📝 Submissions: submit text, URLs and files, with a dry-run preview first
• 💬 Discussions & inbox: read whole threads in one request and message instructors
• 📁 Content: files, pages, modules, lecture captions and full .imscc course export

🧭 How it works

 Your AI app (MCP client)      ──stdio──►  node index.js  ──HTTPS──►  your school's Canvas API
        (starts the server)              (209 tools, runs only
                                          while your app is open)

No web server, no ports, nothing to keep running. Your AI app starts the server when it opens and stops it when it closes.

🚀 Quick start

You need: Node.js 18+ and a Canvas account. There's nothing to download yourself: your AI app fetches the server with npx.

1. Create a Canvas access token

In Canvas, go to Account → Settings → Approved Integrations → + New Access Token. Canvas only shows the token once, so copy it right away. Student tokens usually expire after 30–120 days.

2. Add it to your AI app

Desktop apps

1. Open your app's MCP config file. It's usually under Settings → Developer or Settings → MCP servers, and most apps use an mcpServers JSON block.
2. Add this canvas entry with your token and school address (also in mcp_config.example.json):

    {
      "mcpServers": {
        "canvas": {
          "command": "npx",
          "args": ["-y", "canvas-lms-mcp-local"],
          "env": {
            "CANVAS_API_TOKEN": "your_token_here",
            "CANVAS_BASE_URL": "https://yourschool.instructure.com"
          }
        }
      }
    }

3. Fully quit the app: on Windows, right-click the tray icon and choose Quit; on macOS, press ⌘Q. Then reopen it. Closing the window isn't enough.

Command-line clients

Register this command as a stdio MCP server named canvas, with CANVAS_API_TOKEN and CANVAS_BASE_URL set in its environment:

npx -y canvas-lms-mcp-local

Then check your client's MCP status to confirm it's connected.

3. Try it

Ask your assistant: "Run test_connection." It checks your identity, courses, planner, inbox and missing submissions, and reports any features your school has disabled.

Then try: "What's due this week?", "What do I need on the final to get a B?" or "Which missing assignments hurt my grade the most?"

Prefer running from source?

git clone https://github.com/Fireiscoolsolo/canvas-lms-mcp-local.git
cd canvas-lms-mcp-local
npm install

Copy .env.example to .env in the same folder as index.js, fill in your token and school address, then point your config at the file instead of npx:

{ "mcpServers": { "canvas": { "command": "node", "args": ["C:/Users/YOUR-NAME/Documents/canvas-lms-mcp-local/index.js"] } } }

Forward slashes work on Windows. On macOS, the path looks like /Users/you/canvas-lms-mcp-local/index.js. On Windows, make sure the file is named .env, not .env.txt. To check, turn on View → File name extensions in File Explorer.

⚙️ Configuration

Put settings in the env block of your config, as in step 2. If you run from source, you can use .env next to index.js instead.

| Variable | Required | Default | Description | |---|:-:|---|---| | CANVAS_API_TOKEN | ✅ | — | Your Canvas personal access token | | CANVAS_BASE_URL | ✅ | — | e.g. https://yourschool.instructure.com | | CANVAS_ALLOW_WRITES | | true | false = read-only mode | | CANVAS_PROFILE | | full | core = curated subset of tools | | CANVAS_CACHE_TTL | | 60 | Response cache time in seconds | | CANVAS_TIMEZONE | | system | IANA time zone for due-date math | | CANVAS_DOWNLOAD_DIR | | canvas-downloads next to index.js | Where download tools save files |

🧰 Tools

| Group | Count | Highlights | |---|:-:|---| | Identity | 24 | check_token_expiry, get_rate_limit_status, custom-data storage | | Courses | 16 | permissions, nicknames, favorites | | Assignments | 12 | list_missing_submissions, get_late_policy | | Submissions | 16 | text, URL and file submission, comments, rubric assessments | | Grades | 13 | what_if_grade, compute_needed_score, grade_impact_ranking | | Quizzes | 12 | read-only: dates, attempts, reviews | | Discussions | 17 | get_full_topic_view, replies, ratings | | Inbox | 14 | messaging, find_recipients, threads | | Calendar | 11 | events, office-hours booking | | Content | 33 | files, pages, modules, captions, .imscc export | | Groups | 11 | group workspaces | | Rubrics | 11 | peer reviews | | Search | 3 | smart_search with keyword fallback | | Planning | 11 | get_week_ahead, semester_snapshot, study_priority_ranking | | Meta | 4 | raw_canvas_request for any endpoint not listed above |

🔐 Security

• Nothing is exposed: the server doesn't listen on any port. Only the app that started it can talk to it, through a private pipe.
• Confirmation gate: tools that send, submit, post or delete return a preview first and only act when called with confirm: true.
• Prompt-injection fencing: text other people wrote is wrapped in <<<CANVAS_CONTENT>>> markers and labelled as untrusted.
• No quiz-taking: quiz attempt endpoints are deliberately not included.

Never commit .env. It's already listed in .gitignore. See SECURITY.md.

🎓 Responsible use

This is a study and organization tool. It helps you see deadlines, understand your grades and plan your week. It never takes quizzes, and nothing is sent or submitted until you've seen a preview and confirmed it.

• Follow your school's academic integrity and acceptable-use policies. Some schools restrict personal API tokens or third-party tools.
• Want zero risk of accidental changes? Set CANVAS_ALLOW_WRITES=false for read-only mode.

🛠️ Troubleshooting

Known limits: a student token can't reach admin endpoints, gradebook history, course analytics or quiz statistics. smart_search is a Canvas beta feature and often returns 404.

📄 License

MIT. This project isn't affiliated with Instructure.