Canvas LMS integration for Poke

Connect your Canvas LMS account to Poke by The Interaction Company so you can ask Poke about your classes in plain language:

"What's due this week?" · "Did my CS101 grade change?" · "Read me the syllabus page" · "Any new announcements?"

It's a small FastMCP server that wraps the Canvas REST API and speaks the Model Context Protocol (MCP) Poke connects to. Once deployed, Poke discovers the tools automatically and uses them whenever a question is about your coursework.

All data is read live on every request, so answers always reflect the current state of Canvas — new assignments, changed grades, fresh announcements, updated due dates. There is nothing to re-sync.

What Poke can see

Every resource you asked for, each as an MCP tool Poke calls on demand:

Read-only by design — it never submits, posts, or deletes anything in Canvas.

Setup

Three steps. Fastest path with no signup: ./setup.sh — it installs deps, asks for your Canvas URL + token once, opens a public tunnel, and registers it with Poke for you. Prefer real 24/7 hosting? Full per-host instructions live in HOSTING.md.

1. Get your Canvas access token

In Canvas: Account → Settings → Approved Integrations → "+ New Access Token". Copy it (shown once). Note your Canvas URL — where you log in, e.g. https://canvas.university.edu.

2. Deploy the server — pick one

One-click hosted:

Or local, no signup:

git clone https://github.com/jackulau/PokeCanvas && cd PokeCanvas
./setup.sh

Set CANVAS_BASE_URL + CANVAS_API_TOKEN on whichever host you pick. Every option ends with a URL like https://<host>/mcp — note the /mcp, no trailing slash. Render / Railway / Fly / Heroku / Docker / VPS / tunnel details → HOSTING.md.

Render's free tier sleeps after ~15 min idle (first request after a nap ~50s). Railway/Fly/Heroku or your own Docker host avoid cold starts.

3. Connect it to Poke

Because the credentials live on your server, Poke needs no API key — just the URL.

• One command: npx poke@latest mcp add https://<host>/mcp -n "Canvas"

• Or web UI: poke.com/settings/connections → New integration → Name Canvas, URL https://<host>/mcp, leave the API key blank → Create.

• Or shareable recipe (Poke sets it up for any user from one link): recipe/recipe.md.

Then message Poke "What courses am I taking?"

"Dynamically update if anything changes"

There's no stale cache to worry about: every tool call hits Canvas in real time. Three things make change-tracking explicit:

• get_recent_activity — Canvas's activity stream: new announcements, grade changes, submission comments, discussion replies.

• list_todos / list_upcoming_events — what needs action and what's due, soonest first.

• list_assignments returns your live submission state (graded? late? missing? score?).

Want Poke to proactively ping you when something changes (not just when you ask)? Add a scheduled automation — the recipe in recipe/ includes a ready-to-use prompt for it ("every morning, check get_recent_activity and text me anything new").

Auth modes

Precedence: a token in the request beats the env token; the request base URL (composite or header) beats CANVAS_BASE_URL.

Local development

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt

# Run it
export CANVAS_BASE_URL=https://canvas.youruni.edu
export CANVAS_API_TOKEN=your_token
python src/server.py            # serves http://localhost:8000/mcp

# Verify (no Canvas account needed — uses mocks + a live protocol check)
pytest -q                       # unit tests
python scripts/smoke_tools_list.py   # all tools registered  -> TOOLS_OK
ruff check src tests scripts    # lint

To test the live transport the way Poke sees it:

PORT=8765 python src/server.py &
python scripts/live_http_test.py http://127.0.0.1:8765/mcp   # -> LIVE_OK

Troubleshooting

How it works

Poke  ──(MCP over HTTPS, streamable-http at /mcp)──►  this server  ──(REST + Bearer)──►  Canvas LMS API

• src/server.py — FastMCP app (transport="http", stateless_http=True), registers the tools.

• src/tools.py — the 14 @mcp.tool definitions; build a client from the request, call the data layer, return clean errors.

• src/canvas_api.py — one function per resource; maps to Canvas endpoints and trims responses to what matters.

• src/canvas_client.py — async HTTP, credential resolution, and transparent Canvas Link-header pagination.

See recipe/recipe.md for the Poke recipe and onboarding copy.