内容
# Canvas MCP 服务器
MCP 服务器，由 [FastMCP](https://github.com/jlowin/fastmcp) 构建，用于连接 Claude 到 **Canvas LMS** REST API。配置完成后，您可以用自然语言询问 Claude 关于您的课程、作业、成绩、即将到来的截止日期和公告。
## 向 Claude 公开的工具
| 工具 | 描述 |
| --- | --- |
| `get_courses` | 列出您正在选修的所有活跃课程（id、名称、课程代码、注册类型）。 |
| `get_assignments(course_id)` | 列出某门课程的所有作业（id、名称、截止日期、分数、提交类型）。 |
| `get_assignment_details(course_id, assignment_id)` | 某门作业的完整详情，包括纯文本描述、解锁和锁定日期。 |
| `get_grades(course_id)` | 您在某门课程中的当前成绩/分数，以及已评分的提交列表。 |
| `get_upcoming_events(days_ahead=14)` | 未来 N 天内的即将到来的作业截止日期和日历事件。 |
| `get_announcements(course_id)` | 某门课程的 10 条最新公告，以纯文本显示。 |
| `get_current_user` | 已认证用户的 id、名称和电子邮件 - 便于验证您的令牌。 |
| `get_modules(course_id)` | 某门课程的模块及其项目（页面、作业、文件等）。 |
| `search_course_content(course_id, search_term)` | 在某门课程的作业和模块中搜索某个术语。 |
| `get_course_details(course_id)` | 某门课程的详情，包括教学大纲和学期（已剥离 HTML）。 |
| `get_submission(course_id, assignment_id)` | 您在某门作业中的提交：分数、成绩、状态、迟交/缺交标志以及教师评论。 |
| `get_discussion_topics(course_id)` | 某门课程的讨论主题（不包括公告），以纯文本显示。 |
| `get_discussion_entries(course_id, topic_id)` | 讨论主题的完整线程帖子，包括嵌套回复，以纯文本显示。 |
| `get_overdue_assignments(course_id)` | 某门课程的过期作业（Canvas 的“过期”桶）。 |
| `get_rubric(course_id, rubric_id)` | 某门课程的评分标准和评分。 |
| `get_pages(course_id)` | 列出某门课程的 wiki/内容页面（标题 + 斜杠 + 链接）。 |
| `get_page_content(course_id, page_url)` | 读取 Canvas 页面的完整文本（登录门控页面通过您的令牌获取）。 |
`get_modules` 项目现也公开 `external_url`（外部链接项目的真实外部网站）和 `page_url`（用于 `get_page_content` 的斜杠），除了 Canvas 的 `html_url` - 因此模块链接可以实际打开或读取。
### 写工具（可选 - 默认关闭）
这些工具**修改**Canvas，默认情况下禁用，除非您设置 `CANVAS_ENABLE_WRITES=true`（参见[写操作](#写操作可选））。
| 工具 | 描述 |
| --- | --- |
| `post_discussion_entry(course_id, topic_id, message)` | 在讨论中发布新的顶级条目。 |
| `reply_to_discussion_entry(course_id, topic_id, entry_id, message)` | 回复现有的讨论帖子。 |
| `create_discussion_topic(course_id, title, message)` | 创建新的讨论主题。 |
| `submit_assignment(course_id, assignment_id, submission_type, text?, url?, file_path?)` | 提交作业（`online_text_entry`、`online_url` 或 `online_upload`）。 |
| `post_submission_comment(course_id, assignment_id, comment)` | 评论您自己的提交。 |
| `delete_discussion_entry(course_id, topic_id, entry_id)` | 删除您自己的讨论帖子/回复（不可逆转）。 |
读取工具始终可用。上面的写工具如果未显式启用，则不会执行任何操作 - 它们会返回“写操作已禁用”的消息。
---
## 1. 生成 Canvas API 令牌
您通过个人**访问令牌**向 Canvas 进行身份验证。要创建令牌：
1. 登录到您所在机构的 Canvas 网站（例如，`https://gatech.instructure.com`）。
2. 点击全局导航菜单左侧的 **账户**。
3. 点击 **设置**。
4. 向下滚动到 **批准的集成** 部分。
5. 点击 **+ 新建访问令牌** 按钮。
6. 输入 **用途**（例如，`Claude MCP 服务器`）。您可以将 **过期** 字段留空以获取非过期令牌，或设置过期日期。
7. 点击 **生成令牌**。
8. **立即复制令牌**并将其存储在安全的位置 - Canvas 只会显示一次。如果您丢失了它，则必须生成一个新的令牌。
> 请像对待密码一样保护此令牌。拥有它的人可以在 Canvas 中以您的身份行事。<br>
> 请勿将其提交到 git 或与他人共享。该项目将其存储在 git-ignored 的 `.env` 文件中。
---
## 2. 设置
将这些文件复制或克隆到您计算机上的某个文件夹中，然后从该文件夹中：
### a. 创建您的 `.env`
```bash
cp .env.example .env
```
在 Windows PowerShell 上：
```powershell
Copy-Item .env.example .env
```
打开 `.env` 并填写您的值：
```ini
CANVAS_API_TOKEN=1234~your_real_token_here
CANVAS_BASE_URL=https://gatech.instructure.com
```
将 `CANVAS_BASE_URL` 设置为**您的**机构的 Canvas URL（无尾随 `/api/v1` - 服务器为您附加）。
### b. 安装依赖项
建议使用虚拟环境：
```bash
python -m venv .venv
# macOS/Linux:
source .venv/bin/activate
# Windows PowerShell:
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
---
## 3. 运行服务器
服务器通过 stdio 进行 MCP 通信。您可以以任意一种方式启动它：
```bash
fastmcp run canvas_mcp/server.py
```
或
```bash
python -m canvas_mcp.server
```
如果 `CANVAS_API_TOKEN` 或 `CANVAS_BASE_URL` 缺失，服务器会引发一个明确的 `RuntimeError`，说明需要修复的内容。
当直接运行时，MCP 服务器等待客户端（例如 Claude Desktop）通过 stdio 连接 - 因此它似乎会“挂起”而没有任何输出。这意味着它已正确启动。
---
## 4. 连接到 Claude Desktop（Windows）
Claude Desktop 为您启动服务器，因此一旦配置完成，您通常**不**需要手动运行上述命令。
1. 打开 Claude Desktop 配置文件。在 Windows 上，它位于：
```text
%APPDATA%\Claude\claude_desktop_config.json
```
您可以将该路径粘贴到运行对话框（`Win + R`）或从 Claude Desktop 通过 **文件 → 设置 → 开发者 → 编辑配置** 打开。
2. 在 `mcpServers` 下添加一个 `canvas` 条目。直接在 **`env`** 块中传递您的 Canvas 凭证 - 这样 Claude Desktop 会在服务器的环境中设置它们，您**不需要**单独的 `.env` 文件。替换路径和值为您自己的：
```json
{
"mcpServers": {
"canvas": {
"command": "C:\\Users\\YourName\\projects\\canvas-mcp\\.venv\\Scripts\\python.exe",
"args": [
"-m",
"canvas_mcp.server"
],
"cwd": "C:\\Users\\YourName\\projects\\canvas-mcp",
"env": {
"CANVAS_BASE_URL": "https://your-school.instructure.com",
"CANVAS_API_TOKEN": "YOUR_TOKEN_HERE"
}
}
}
}
```
注意：
- 在 Windows 上所有 JSON 路径都使用**双反斜杠** (`\\`)。
- `env` 块是推荐的 `CANVAS_BASE_URL` 和 `CANVAS_API_TOKEN` 供应方式 - 服务器直接从其环境中读取它们，因此当以这种方式启动时，`.env` 文件是可选的。
- `command` 应该是 Python 解释器。使用项目的 `.venv\\Scripts\\python.exe` 可以保证安装的依赖项在路径上。纯粹的 `"python"` 也**仅在**您的 PATH 上并且已安装所需依赖项时有效。
- `cwd` 必须指向项目根目录（包含 `canvas_mcp` 包的文件夹），以便 `python -m canvas_mcp.server` 可以导入它。
3. 保存文件。
---
## 5. 验证它是否有效
1. **完全退出** Claude Desktop（右键单击系统托盘图标 → 退出）并重新打开。配置更改仅在全新启动时生效。
2. 打开一个新的聊天窗口。点击消息框中的工具/插件图标 - 您应该看到 **canvas** 已列出及其工具。
3. 询问类似：
> “我当前在 Canvas 中以谁的身份登录？”
Claude 应该调用 `get_current_user` 并返回您的姓名 - 一个快速的令牌检查。然后尝试：
> “本学期我选修了哪些课程？”
Claude 应该调用 `get_courses` 并用您的课程列表回复。
4. 跟进，例如：
> “下周有哪些作业到期？”
以便使用 `get_upcoming_events`。
### 故障排除
- **服务器未列出/Claude 中的红色错误：** 打开 Claude Desktop 中的 **设置 → 开发者** 并查看 MCP 日志，或检查 `%APPDATA%\Claude\logs\`。
- **`RuntimeError: CANVAS_API_TOKEN 未设置：`** `env` 块在您的 `claude_desktop_config.json` 中缺失（或如果您手动运行它，则您的 `.env` 缺失/不在您配置的 `cwd` 中）。
- **工具输出中的 HTTP 401 错误：** 令牌错误、过期或已撤销 - 生成一个新的令牌（第 1 节）。
- **HTTP 404 错误：** 仔细检查 `course_id` 并确保 `CANVAS_BASE_URL` 与您的机构匹配。
---
## 写操作（可选）
默认情况下，此服务器是**只读**的 - 它可以查看 Canvas 但永远不会更改它。写工具（`post_discussion_entry`、`reply_to_discussion_entry`、`create_discussion_topic`、`submit_assignment`、`post_submission_comment`、`delete_discussion_entry`）在您显式启用它们之前被禁用。
### 启用写入
1. 在您的 `.env` 中设置开关:
```ini
CANVAS_ENABLE_WRITES=true
```
（或者，如果您通过 `claude_desktop_config.json` 中的 `env` 块配置服务器，请添加 `"CANVAS_ENABLE_WRITES": "true"`。）
2. **完全重启** Claude Desktop / 您的 MCP 客户端 - 开关在启动时读取一次。
当写入被禁用时，每个写入工具仅返回一条“写入已禁用”的消息并且不进行网络调用。
### 请在启用前阅读
- ⚠️ **这些操作是真实且大多不可逆的。** 发布讨论回复或提交作业对您的教师和同学可见。像您自己点击“提交”一样对待它。
- ⚠️ **写入不是幂等的。** 如果工具调用被重试，它可以发布两次或提交两次。请查看 Claude 即将执行的操作。
- **开关是全局的。** `.env` 被所有启动此服务器的客户端（Claude Desktop 和 Claude Code）共享，因此启用写入功能会在所有地方启用。
- **`submit_assignment`** 需要作业实际接受的 `submission_type`：`online_text_entry`（传递 `text`）、`online_url`（传递 `url`）或 `online_upload`（传递绝对 `file_path`）。
### 安全测试写入
因为写入会创建真实内容，所以请用您**选择**的低风险内容进行测试 - 例如，在您不介意编辑的练习/介绍讨论中发布简短回复，然后在 Canvas 中删除它。不要通过提交真正的评分作业来测试。
---
## 项目结构
```text
canvas_mcp/
__init__.py # 包标记（空）
server.py # FastMCP 应用程序 + 所有六个工具
requirements.txt # 固定的依赖项
.env.example # 您的 .env 模板（复制到 .env）
.env # 您的机密（git-ignored，永不提交）
README.md # 此文件
```
## 许可证
免费提供用于个人/教育用途。您负责遵守您所在机构的 Canvas API 使用政策。
