EduBase

EduBase MCP 服务

此代码库包含 Model Context Protocol（MCP）服务的实现，适用于 EduBase 平台。它允许 MCP 客户端（例如 Claude Desktop）和大模型与你的 EduBase 账户交互，并代表你执行任务。它支持 stdio、SSE 和 streamable HTTP 传输协议。

什么是 EduBase？

EduBase 是一个创新的模块化在线教育平台，让学习更有趣、更简单、更具互动性，适用于教育机构或企业。

为什么选择 EduBase？

EduBase 凭借其独特的功能组合，革新了数字学习：

• 高级测验系统，支持参数化，可生成同一题目的无限变体；具备实时作弊检测、精美的 LaTeX 排版、高级 STEM 支持和自动评分功能
• 统一学习环境，在一个直观的系统中集中管理所有教育内容——视频、考试、文档和 SCORM 模块
• 企业级安全性，提供 SSO 集成、精细化访问控制、全面审计和 GDPR 合规等功能
• 集成能力，可通过 LTI、全面的 API 和自定义集成选项连接现有系统
• AI 辅助工具，例如 EduBase Assistant，可即时将现有内容转换成交互式测验和评估，或将材料从一种语言翻译成另一种语言

从高等教育机构到企业培训部门，EduBase 都能满足你的特定需求，并在所有设备上提供直观的用户体验。

演示视频

与 Claude 协作创建和上传题目、安排考试并分析用户结果：

获取 API 凭据

登录后，在 Dashboard 中找到 Integrations 菜单，点击“add integration”，然后选择“EduBase API”类型。

如果你看不到此选项，请输入 MCPGITHUB 激活码，或随时通过 [email protected] 联系我们申请访问权限。

工具

每个已记录的 API 端点都可作为工具使用，命名格式为 edubase_<method>_<endpoint>。例如，GET /user:me 端点对应的工具名为 edubase_get_user_me。标签、权限和转移端点对每种内容类型的工作方式都相同，因此每种方法共用一个带有 type 参数的工具（例如，POST /exam:tag、POST /quiz:tag 等对应的工具为 edubase_post_content_tag）。更多信息请参阅我们的开发者文档。

工具集

工具按工具集分组，因此你可以只开放所需的工具。工具越少，占用的模型上下文就越少，也更便于模型选择合适的工具。默认情况下，每个工具集都已启用。

工具集	用途
files	临时文件上传（始终启用）
questions	问题
quizzes	测验集、测验题目、设置和评分预设
exams	考试、考试设置、用户、证书、品牌和流程
results	测验和考试结果、证书下载
users	用户、用户姓名、群组和登录链接
classes	班级和班级成员关系
organizations	组织、成员、部门、职位、能力和 Webhook
integrations	集成及其密钥
tags	内容的标签及标签附件
permissions	用户对内容的权限和所有权转移
metrics	自定义指标

使用逗号分隔的列表在 EDUBASE_TOOLSETS 中选择工具集（例如 questions,quizzes,exams）。将 EDUBASE_READONLY=true 设为只开放读取数据的工具（get 工具，以及仅生成下载链接的工具，例如 edubase_post_question_export）。

将 EDUBASE_DYNAMIC_TOOLSETS=true 设为按需启用工具集：会话启动时仅包含关键工具，模型可通过 edubase_enable_toolsets 工具启用所需的工具集（该工具列于 edubase_list_toolsets 中）。这会让初始工具列表保持精简，适用于启动时会加载所有工具的客户端；但客户端需要在收到变更通知时刷新工具列表。

使用 HTTP 传输时，客户端可以通过 EduBase-Mcp-Toolsets、EduBase-Mcp-ReadOnly 和 EduBase-Mcp-Dynamic 请求头，或 toolsets、read_only 和 dynamic_toolsets 查询参数，进一步缩小当前会话的配置范围（例如 https://domain.edubase.net/mcp?toolsets=exams&read_only=true）。会话无法启用服务配置中已禁用的工具集或写入工具。

提示词

提示词是现成的工作流，可从 MCP 客户端启动（例如，从 + 或 / 菜单启动）。支持补全的客户端会在你输入时为参数建议取值：题型，以及你自己的考试、测验集和班级。

提示词	功能	参数
创建题目（edubase_prompt_create_question）	编写新题目并发布到你的 QuestionBase	type、subject，以及可选的 difficulty 和 language
根据文档创建题目（edubase_prompt_questions_from_document）	将附加的文档（或文件路径或 URL）转换为题目；你批准方案后，还可选择将题目加入测验集	document，以及可选的 questions（数量）、types、quiz 和 language
创建考试（edubase_prompt_create_exam）	生成有关某个主题的题目，将其收集到新的测验集中，并据此创建考试	topic、questions（数量），以及可选的 types（逗号分隔）、language 和 schedule
创建包含学习旅程的考试（edubase_prompt_create_exam_journey）	按上述方式创建考试，然后据此构建并发布简短的考试学习旅程，重用你账户中的相关考试，并在需要时创建练习测验集和后续考试	与 创建考试 相同
复制考试（edubase_prompt_copy_exam）	使用相同的测验集和设置，在新的时间段内创建考试	exam、schedule，以及可选的 title
将班级分配到考试（edubase_prompt_assign_class_to_exam）	将班级中的活跃成员分配到考试	exam、class
总结考试结果（edubase_prompt_summarize_exam_results）	分析考试结果，并可选择将总结保存到考试中	exam，以及可选的 focus 和 save（ask、yes 或 no）
检查考试学习旅程（edubase_prompt_exam_journey_status）	显示用户在考试学习旅程中的进度，以及哪些用户遇到了阻碍	exam

仅在启用相应工具集时才会提供提示词；在只读模式下，仅提供最后两项。

如果考试的题型留空，支持引导式输入的客户端会通过复选框询问题型。这些客户端还会在执行不可撤销的更改之前要求你确认（删除考试、测验集、题目、用户、组织和集成，转移所有权，开始新一轮考试，以及轮换集成密钥）。设置 EDUBASE_ELICITATION=false 可关闭这些询问。

用于创建或更改考试、测验集和学习旅程的工具会链接到它们在 EduBase 中的页面。

资源

参考文档可作为资源使用，也可通过 edubase_mcp_reference 工具供无法读取资源的模型使用：edubase://reference/questions（题目字段和类型）和 edubase://reference/exam-journeys（可移植的考试学习旅程格式）。对于没有相关技能的客户端，这些文档涵盖了 EduBase 技能所说明的内容。考试和测验集也可作为资源附加（edubase://exam/{exam} 和 edubase://quiz/{quiz}），并会列出及推荐其中的内容。可通过 EDUBASE_CONTENT_RESOURCES=false 关闭这些资源；也可针对单个会话使用 EduBase-Mcp-Content-Resources: false 标头、content_resources=false 查询参数或 Smithery 设置 edubaseContentResources 关闭。

用于创建或更改考试、测验集和学习旅程的工具会链接到它们在 EduBase 中的页面。

配置

可使用环境变量配置 MCP 服务。可用变量如下：

变量	描述	必填	默认值
EDUBASE_API_URL	EduBase API 的基础 URL，通常为 https://subdomain.edubase.net/api。	是	https://www.edubase.net/api
EDUBASE_API_APP	你在 EduBase 上的集成应用的 App ID，即 EduBase API 中的 app。可在 EduBase 的集成详情窗口中找到。	使用带身份验证的 HTTP 传输时不需要，否则 是	-
EDUBASE_API_KEY	你在 EduBase 上的集成应用的 Secret key，即 EduBase API 中的 secret。可在 EduBase 的集成详情窗口中与 App ID 一起找到。	使用带身份验证的 HTTP 传输时不需要，否则 是	-
EDUBASE_SSE_MODE	以带 SSE 传输的 HTTP 模式启动 MCP 服务。值必须为 true。	否	false
EDUBASE_STREAMABLE_HTTP_MODE	以带可流式 HTTP 传输的 HTTP 模式启动 MCP 服务。值必须为 true。	否	false
EDUBASE_TOOLSETS	启用的工具集列表，以逗号分隔；也可以设为 all。	否	all
EDUBASE_READONLY	仅公开读取数据的工具。值必须为 true。	否	false
EDUBASE_OUTPUT_SCHEMAS	工具的输出架构和结构化工具结果：off 表示列出工具时不包含输出架构，且仅以 JSON 文本形式返回结果；on 表示包含完整的输出架构；fields 表示包含输出架构，但不含字段描述（保留结构化结果，同时节省架构所需的大部分令牌）。	否	fields
EDUBASE_CONFIG_PROVIDERS	HTTP 传输启用时，允许在请求中提供会话配置的托管服务商列表，以逗号分隔。目前仅支持 smithery（采用 base64 编码的 config 查询参数）。	否	-
EDUBASE_CONTENT_RESOURCES	将账户的考试和 Quiz 集列为资源。设为 false 可关闭此功能，例如在没有凭据时检查服务。参考文档仍可用。	否	true
EDUBASE_DYNAMIC_TOOLSETS	启动会话时仅启用文件上传工具，并允许模型按需启用工具集。值必须为 true。	否	false
EDUBASE_ELICITATION	如果客户端支持请求用户输入，则通过客户端请用户确认无法撤销的更改，并选择提示词的问题类型。设为 false 可关闭此功能。	否	true
EDUBASE_HTTP_PORT	使用 SSE 或可流式 HTTP 传输模式时，HTTP 服务将监听此端口。	否	3000
EDUBASE_OAUTH	启用 OAuth 2.1 受保护资源行为：未通过身份验证的请求将被拒绝，并返回指向 /.well-known/oauth-protected-resource/mcp 的 401 + WWW-Authenticate；同时会将 bearer 令牌转发到 EduBase API。	否	false
EDUBASE_OAUTH_AUTHORIZATION_SERVER	作为 OAuth IdP 的 EduBase 部署的公开基础 URL。用于在受保护资源元数据文档中公布授权服务器。	否	根据 EDUBASE_API_URL 推导
EDUBASE_OAUTH_RESOURCE_URL	此 MCP 服务的公开基础 URL（OAuth 资源指示符）。用于 WWW-Authenticate 标头和资源元数据。	否	根据 EDUBASE_API_URL 推导
EDUBASE_ALLOW_PRIVATE_NETWORK	使用 HTTP 传输时，edubase_filebin 工具会阻止向私有、环回、链路本地和保留地址发起出站请求（SSRF 防护），并拒绝本地文件路径。设为 true 可允许这些操作，例如在受信任的专用网络上进行可自托管部署。在 stdio 模式下无效，因为本地用户是唯一的调用方。	否	false
EDUBASE_FILEBIN_ALLOWED_HOSTS	可选的主机名允许列表，以逗号分隔；允许这些主机名作为 edubase_filebin 上传目标（精确匹配主机名或任意子域名，例如 edubase.net）。为空时允许任何公共主机（仍受上述地址筛选限制）。	否	-

用作远程 MCP 服务

你可以将 EduBase MCP 服务用作 MCP 客户端的远程 MCP 服务。为此，你需要将 MCP 服务托管在客户端可以访问的位置，然后配置客户端以连接到该服务。启动时请使用 SSE 或可流式传输的 HTTP 传输模式；通过互联网远程访问服务时，务必使用 HTTPS！

远程服务身份验证

你可以通过两种模式使用此服务：

• 不进行客户端身份验证：在此模式下，服务不会要求客户端进行任何身份验证。这适用于测试或开发，也适用于封闭网络，但不建议用于生产环境。使用此模式时，还必须使用 EDUBASE_API_APP 和 EDUBASE_API_KEY 配置服务！
• 使用 Bearer 令牌身份验证：在此模式下，每个请求都必须携带 Bearer 令牌。推荐在生产环境中使用此模式。你可以在 EduBase 账户中创建集成应用，并按 {app}:{secret} 格式提供 App ID 和 Secret key，再将其进行 Base64 编码作为令牌，以获取 Bearer 令牌。服务随后会使用此令牌对客户端进行身份验证，并授权其访问 API 端点。
• 使用 OAuth 2.1（EduBase 作为 IdP）：启用 EDUBASE_OAUTH=true 后，兼容的客户端（Claude Desktop、Claude.ai connectors、Cursor、ChatGPT connectors 等）会通过 /.well-known/oauth-protected-resource 发现 EduBase 授权服务器，动态注册自身（RFC 7591），引导用户完成 EduBase 授权页面，并使用 PKCE S256 将授权码兑换为不透明访问令牌。MCP 服务会将该令牌原样转发给 EduBase API，由后者将其解析为首次授权时自动创建的 MCP 集成。无需复制 App ID/Secret——用户只需在客户端中点击“Connect EduBase”。

在 Claude Desktop 中使用

如需分步操作指南，请参阅我们的博客文章：将 EduBase 连接到 Claude：完整的 MCP 集成指南。

使用提供的 EduBase MCP 服务

如果提供的 EduBase MCP 服务可用，你无需进行任何配置，只需在客户端中将其添加为远程服务，并使用 URL https://domain.edubase.net/mcp（替换为实际域名）；如果客户端支持 OAuth 身份验证，也可以在 Authorization 标头中提供相应的 Bearer 令牌（Authorization: Bearer ${BASE64_ENCODED_TOKEN}）。

推荐 www.edubase.net 用户使用，因为该服务由我们维护和更新，你无需操心托管或配置。连接客户端时，只需确保使用正确的 URL 和身份验证方式。

手动安装

将以下内容添加到 claude_desktop_config.json：

使用 Node.js

运行 MCP 服务前，请确保已安装 Node.js。你可以从 nodejs.org 下载，也可以使用 brew 等软件包管理器。

{
  "mcpServers": {
    "edubase": {
      "command": "npx",
      "args": [
        "-y",
        "@edubase/mcp"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

或者下载 EduBase MCP 服务的发行版本，或克隆代码库并运行 npm run build 来构建服务。别忘了将 /path/to/dist 调整为实际目录，并配置环境变量！

{
  "mcpServers": {
    "edubase": {
      "command": "node",
      "args": [
        "/path/to/dist/index.js"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

使用 Docker

运行 MCP 服务前，请确保已安装并启动 Docker。你可以从 docker.com 下载，也可以使用软件包管理器。别忘了配置环境变量！

{
  "mcpServers": {
    "edubase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "EDUBASE_API_URL",
        "-e",
        "EDUBASE_API_APP",
        "-e",
        "EDUBASE_API_KEY",
        "edubase/mcp"
      ],
      "env": {
        "EDUBASE_API_URL": "https://domain.edubase.net/api",
        "EDUBASE_API_APP": "your_integration_app_id",
        "EDUBASE_API_KEY": "your_integration_secret_key"
      }
    }
  }
}

通过远程 MCP 服务安装

如果提供的 EduBase MCP 服务可用，你可以将其用作远程服务。我们建议将 EDUBASE_API_APP 和 EDUBASE_API_KEY 进行 Base64 编码，并在 Authorization 标头中将其用作 Bearer 令牌（Authorization: Bearer ${BASE64_ENCODED_TOKEN}）。

{
  "mcpServers": {
    "edubase": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://domain.edubase.net/mcp",
        "--header",
        "Authorization: Bearer ${EDUBASE_API_APP}:${EDUBASE_API_KEY}"
      ]
    }
  }
}

通过 Smithery 安装

如需通过 Smithery 自动为 Claude Desktop 安装 EduBase MCP server：

npx -y @smithery/cli install @EduBase/MCP --client claude

开发

运行 npm test 可构建服务并检查工具列表：检查工具列表和服务说明的大小预算、工具描述、工具集、只读和动态工具集模式，以及 HTTP 传输的配置处理。新增工具超出预算时，请缩短其架构，或在 test/server.test.mjs 中有意提高预算，因为每个客户端在每个会话中都要承担工具列表的开销。

src/references 中的参考文档根据 EduBase 开发者文档生成。当问题字段或考试流程格式发生变化时，请运行 node scripts/sync-references.mjs <path to the developer documentation repository> 重新生成这些文档。

文档同步节点： 工具、提示词和参考文档最后一次同步时间为 2026-10-26，依据的是 开发者文档 中的提交 fe995a62a2（组织权限改进），并与 EduBase develop 分支的提交 9fd4968d26（组织成员限制，发布 8.6.0 后）进行了核对。 如需更新服务，请在开发者文档仓库中运行 git log --oneline fe995a62a2..HEAD 和 git diff fe995a62a2..HEAD -- docs/api/endpoints，并在 EduBase 仓库中运行 git log --oneline 9fd4968d26..HEAD -- system/do/api.do.php，更新 src/tools 中受影响的工具（以及对应的提示词和工具集指南），重新生成参考文档，并将此标记更新为新的 HEAD 提交。两者存在差异时，以 EduBase 仓库为准。

联系方式

网站：www.edubase.net
开发者文档：developer.edubase.net
电子邮件：[email protected]