LearnWorlds

ohneben 的 LearnWorlds MCP

---

许可证与检查

MCP 注册目录

使用自然语言，通过 Claude、Cursor 等 AI 助手以及任何其他 MCP 客户端管理你的 LearnWorlds 学校。

这个 Model Context Protocol 服务开放了 LearnWorlds 公共 API——全部 94 个端点，直接根据 OpenAPI 规范生成 MCP 工具。每个工具都经过安全分类 （🟢 只读 / 🟡 写入 / 🔴 破坏性操作），让助手在调用之前就了解操作的作用。它支持 stdio（Claude Desktop 和其他本地启动器） 或 Streamable HTTP（托管于 Docker），并配备重试、客户端限流和请求超时机制，确保在实际运行的学校中也能稳定工作。

为什么你会需要它

有些 MCP 服务只是转发 API。这个服务的设计目标是可以放心交给大模型使用，并且易于在实际环境中运行：

你会获得什么	这为何重要
全部 94 个端点，由规范驱动	全面覆盖课程、用户、注册、付款、订阅、优惠券、证书、席位、社区和报告——没有挑选遗漏。
每个工具都有安全类别 🟢 / 🟡 / 🔴	每个工具描述顶部的横幅都会明确告诉模型它的操作——读取、创建、更新或删除——然后模型才会执行。
描述面向 Agent，而非人类	每个工具都会说明其副作用、身份验证和速率限制行为、返回结构、错误代码、哪些情况下不应使用它，以及可替代它的同类工具。
机器可读的 MCP 注解 (readOnlyHint, destructiveHint)	支持注解的宿主（包括 Claude）可以自动信任读取操作，并在执行任何破坏性操作前要求确认。
自动重试并采用退避策略	对瞬时 429 / 5xx 响应进行重试，并采用带抖动的指数退避，同时遵循服务器的 Retry-After 标头。
内置速率限制	在 LearnWorlds 的 30 requests / 10 s 限制下自动调节速率，确保工具调用突发时不会触发 429。
每次请求均有超时限制	上游调用挂起时会中止并重试，而不是让服务冻结。
两种传输方式：stdio 和 Streamable HTTP	可在 Claude Desktop 中本地使用，也可运行一个始终在线的服务，供任意数量的 MCP 客户端通过 HTTP 访问。
Docker + docker-compose、健康检查、自动重启	开箱即用的生产级部署：运行 docker compose up，服务便会持续运行。
HTTP 端点上的 Bearer 令牌身份验证	只要服务绑定到环回地址以外的地址，就必须进行身份验证：如果没有 MCP_AUTH_TOKEN，服务会拒绝启动，而不是暴露未受保护的 API。
密钥绝不会传给模型	凭据保存在服务的环境中，并在每次请求时注入——助手只能看到工具输入和 API 响应。
直接替换规范即可更新	LearnWorlds 发布了更新的 YAML？替换一个文件并重新构建——新端点会自动成为新工具，无需更改代码。

对比

在撰写本文时，这似乎是唯一专门针对 LearnWorlds 的 MCP 服务。 你也可以改用通用 OpenAPI→MCP 包装器来加载规范——但这样会缺少以下功能：

功能	本项目	通用 OpenAPI→MCP 包装器*
将全部 94 个 LearnWorlds 端点作为工具	✅	✅
每个工具的 🟢 / 🟡 / 🔴 安全类别和横幅	✅	❌
readOnlyHint / destructiveHint MCP 注解	✅	➖
$ref 解引用 + 支持递归的架构	✅	➖
自动重试 429 / 5xx（遵循 Retry-After）	✅	❌
客户端速率限制（保持在 30 req / 10 s 以内）	✅	❌
每次请求均有超时限制并支持中止	✅	➖
stdio 传输方式	✅	✅
Streamable-HTTP 传输方式	✅	➖
Docker + docker-compose、健康检查、自动重启	✅	❌
强制执行的 Bearer 令牌身份验证	✅	❌
凭据在服务端注入，绝不发送给模型	✅	➖
许可证	MIT	不一

_{*通用 OpenAPI→MCP 包装器可将任意 Swagger/OpenAPI 规范转换为 MCP 工具。它们可以访问相同的端点，但会以相同方式处理每项操作——没有安全类别、没有弹性机制、没有部署方案，也没有针对真实学校数据的防护措施。“➖” = 视工具而定 / 不保证。数据快照日期：2026 年 7 月。}

你可以做什么

连接后，可以向助手提出以下请求：

• “列出本月注册的最近 10 位用户。”
• “为 [email protected] 创建用户，并将她加入 ‘Pro’ 套餐。”
• “显示本月的付款和总收入。”
• “哪些用户还没有完成 ‘Onboarding’ 课程？”
• “为年度订阅计划创建一个 20% 折扣优惠券。”
• “提取最受欢迎的 5 门课程的完成情况分析数据。”

工具会根据 API 自动生成，并分为 🟢 只读、🟡 写入和 🔴 破坏性操作三类，因此行为得当的宿主可以区别对待各类工具。

工作原理

Claude / Cursor / any MCP client  ──MCP──►  this server  ──HTTPS──►  LearnWorlds API (your school)

服务会将捆绑的 OpenAPI 规范解析为 MCP 工具（解析 $ref 并防止递归架构），为每个工具标记安全类别，并在每个传出请求中注入你的 bearer token 和 Lw-Client 标头。你的凭据会保留在服务的环境中，大模型不会看到或处理这些凭据。

要求

• 具备 API 访问权限的 LearnWorlds 学校——需要访问令牌和客户端 ID （管理员 → 设置 → 集成 → 开发者），以及学校的 API 基础 URL。 请参阅获取 API 凭据。
• 快速开始需要 Docker（macOS/Windows 上使用 Docker Desktop）——或者需要 Node.js ≥ 18，才能从源代码运行。

快速开始（Docker）

1. 添加凭据。 复制示例配置并填写：

cp .env.example .env
# edit .env → set LEARNWORLDS_BASE_URL, LEARNWORLDS_API_TOKEN, LEARNWORLDS_CLIENT_ID
#           → set MCP_AUTH_TOKEN (required once the port is published beyond
#             127.0.0.1): openssl rand -hex 32

2. 启动服务：

docker compose up -d --build

随附的 docker-compose.yml 仅绑定到 127.0.0.1:8765，因此你的计算机可以访问该服务，但网络中的其他设备无法访问。

3. 确认服务正在运行：

curl -s http://localhost:8765/health
# → {"status":"ok","server":"learnworlds-mcp","tools":94}

4. 连接 MCP 客户端。 MCP 端点为 http://localhost:8765/mcp。

• Claude Desktop——添加一个指向该 URL 的自定义连接器（设置 → 连接器），或使用 mcp-remote 在本地桥接。 在配置的 mcpServers 下添加以下内容，然后完全退出并重新打开应用：

  {
    "mcpServers": {
      "learnworlds": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "http://localhost:8765/mcp",
          "--header", "Authorization: Bearer YOUR_MCP_AUTH_TOKEN"
        ]
      }
    }
  }
  

  （如果将 MCP_AUTH_TOKEN 留空，请删除 --header 这一行。）

• Claude Code——运行一条命令：

  claude mcp add --transport http learnworlds http://localhost:8765/mcp
  

• Claude Cowork——与 Claude Code 共用 MCP 配置，因此运行上述命令后，这些工具也会在 Claude Cowork 中可用。

想使用预构建镜像？

每次推送到 main 时，都会向 GitHub Container Registry 发布可直接运行的镜像，因此你可以完全跳过本地构建：

docker run -d --name learnworlds-mcp -p 127.0.0.1:8765:8765 --env-file .env \
  ghcr.io/ohneben/learnworlds-mcp:latest

获取 API 凭据

1. 登录 LearnWorlds 学校管理后台。
2. 前往设置 → 集成 → 开发者（API 页面）。
3. 将访问令牌复制到 LEARNWORLDS_API_TOKEN，并将客户端 ID复制到 LEARNWORLDS_CLIENT_ID。
4. 将 LEARNWORLDS_BASE_URL 设置为学校的 API 基础 URL： https://<your-school>.learnworlds.com/admin/api。如果学校使用自定义域名，请改用该域名（例如 https://academy.example.com/admin/api）。

将这三项都填入 .env。服务会在每个请求中注入这些值，因此助手永远不会看到它们。

配置

所有配置都写在 .env 中（从 .env.example 复制）：

变量	必填	默认值	描述
LEARNWORLDS_BASE_URL	✅	—	学校的 API 基础 URL
LEARNWORLDS_API_TOKEN	✅	—	Bearer 访问令牌
LEARNWORLDS_CLIENT_ID	✅	—	作为 Lw-Client 请求头发送
MCP_TRANSPORT	—	stdio	stdio 或 http（Docker 镜像默认使用 http）
PORT	—	8765	HTTP 监听端口
HOST	—	0.0.0.0	HTTP 绑定地址
MCP_HTTP_PATH	—	/mcp	HTTP MCP 路由
MCP_AUTH_TOKEN	⚠️	(off)	要求在 /mcp 上提供 Authorization: Bearer <token>。当 HOST 不是环回地址时，此项为必填，否则服务会拒绝启动。此变量在 1.1.0 中由 MCP_SHARED_TOKEN 重命名而来
MCP_ALLOWED_HOSTS	—	(automatic)	以逗号分隔的主机名列表，用于指定 Host 请求头中可接受的主机名（DNS 重绑定防护）。在反向代理后运行时需要设置
MCP_ALLOW_INSECURE	—	(off)	取消启动拒绝。仅适用于其他人无法访问的端点
MCP_SESSION_TTL	—	1800	会话闲置多少秒后将被丢弃
MCP_MAX_SESSIONS	—	256	最大并发会话数
MCP_BODY_LIMIT	—	25mb	可接受的最大请求正文大小
LEARNWORLDS_MAX_REQUESTS	—	25	每个时间窗口内客户端请求数（0 表示禁用限流）
LEARNWORLDS_RATE_WINDOW_MS	—	10000	限流时间窗口，单位为 ms
LEARNWORLDS_MAX_RETRIES	—	3	遇到 429 / 5xx / 网络错误时的重试次数
LEARNWORLDS_TIMEOUT_MS	—	30000	每次尝试的请求超时时间
LEARNWORLDS_OPENAPI_PATH	—	(bundled)	加载其他 OpenAPI YAML 文件

修改 .env 后，运行 docker compose up -d --force-recreate 重新加载。

工具安全类别

每个工具的描述都以以下横幅之一开头，并带有对应的 MCP 注解：

横幅	数量	readOnlyHint	destructiveHint	含义
🟢 只读	59	true	false	仅获取数据。安全。
🟡 写入 · 创建数据	—	false	false	POST — 创建记录（非幂等；可能产生重复记录）。
🟡 写入 · 更新数据	—	false	false	PUT — 原位修改现有记录（幂等）。
🔴 破坏性操作 · 删除	8	false	true	DELETE — 删除一条记录。请先确认。

🟡 写入工具共 27 个（17 个创建 + 10 个更新）。遵循注解的宿主（包括 Claude）可以要求确认具有 destructiveHint 的工具，并自动信任具有 readOnlyHint 的工具。

每个描述都采用相同的布局，位于横幅下方，让 Agent 首次阅读时就能采取行动，而不必先试探：

行	说明内容
(用途)	端点的功能，直接取自 OpenAPI 规范，只说明一次。
行为	调用对实际运行中的学校系统有何影响、是否幂等，以及如何处理身份验证、限流和重试。
参数	仅说明输入架构无法表达的内容 — body 包装器、分页及任何重命名的参数。
返回值	HTTP <status> + JSON 结果结构，以及可能返回的错误代码。
使用时机	何时使用、何时不使用，以及同一领域中最多五个相关工具。

随时运行 npm run list-tools（无需凭据）即可打印完整目录和各类别的数量。

各领域覆盖情况（读取 / 写入 / 删除）

领域	🟢 读取	🟡 写入	🔴 删除
用户	10	7	1
联盟合作伙伴	7	1	0
社区	6	3	2
课程	5	3	0
促销（优惠券）	4	3	0
报告	4	0	0
付款	3	0	0
多席位	3	3	2
用户组	3	3	2
套装	2	0	0
评估	2	1	0
订阅计划	2	0	0
证书	1	1	1
用户订阅	1	0	0
用户角色	1	0	0
分期付款	1	0	0
潜在客户	1	0	0
日历	1	0	0
事件日志	1	0	0
异步操作	1	0	0
更新用户进度	0	2	0
总计	59	27	8

从源代码运行（stdio，无 Docker）

更喜欢在 Claude Desktop 中使用传统的 stdio 模式？在本地构建：

npm install
npm run build

然后在 claude_desktop_config.json 中将 Claude Desktop 指向编译后的入口点：

{
  "mcpServers": {
    "learnworlds": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/Learnworlds-MCP/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "LEARNWORLDS_BASE_URL": "https://your-school.learnworlds.com/admin/api",
        "LEARNWORLDS_API_TOKEN": "your-access-token",
        "LEARNWORLDS_CLIENT_ID": "your-client-id"
      }
    }
  }
}

保持规范为最新

随附的 spec/learnworlds-openapi.yaml 是这些工具的事实来源。若要根据较新版本的 API 刷新，将新的 YAML 文件放到原位置（或将 LEARNWORLDS_OPENAPI_PATH 指向该文件），然后重新构建：

docker compose up -d --build   # Docker
# or
npm run build                  # from source

新的路径会自动成为新工具 — 无需更改代码。

开发

npm install
npm run build      # compile TypeScript → dist/
npm test           # run the Vitest suite
npm run list-tools # print the categorized tool catalog (no credentials needed)

CI 会在 Node 20 和 22 上构建并测试每次推送；推送到 main 时，还会向 GitHub Container Registry 发布 Docker 镜像。如果 server.json 中的版本尚未列入官方 MCP Registry，同一轮运行也会将其发布到该注册表。

备注与约定

• 传输方式：本地启动器默认使用 MCP_TRANSPORT=stdio；Docker 镜像运行的常驻 Streamable-HTTP 服务使用 MCP_TRANSPORT=http。
• 分页：大多数 get 工具都接受 page（以及特定端点的筛选条件）；LearnWorlds 会对列表响应分页（通常每页 20–50 项）。
• 速率限制：LearnWorlds 允许每 10 秒发送 30 个请求；服务会按照 LEARNWORLDS_RATE_WINDOW_MS 时间窗口内的 LEARNWORLDS_MAX_REQUESTS 值自行限流（默认为每 10 秒 25 个请求），并重试收到的任何 429 响应。
• 请求正文：写入工具接受 body 参数；其架构会根据规范解析并展示给模型。

安全

• 你的 API 凭据仅保存在 .env 中，该文件已加入 git 忽略。**切勿提交真实密钥。**如果令牌泄露，请在 LearnWorlds 管理后台 → Settings → Integrations → Developers (API) 中轮换令牌。
• HTTP 端点一旦绑定到 loopback 以外的地址，就必须使用令牌。 如果未设置 MCP_AUTH_TOKEN，服务将拒绝启动，并说明该怎么做。请通过 Authorization: Bearer <token> 标头发送令牌，最好在 TLS 后运行。
• **本地也一样：**如果未设置令牌，Host 标头将被限制为 localhost 名称，因此网页无法通过 DNS 重绑定访问该端点。仅绑定到 loopback 并不能提供保护。若在反向代理后运行，请设置 MCP_ALLOWED_HOSTS。
• 在反向代理后运行时，请在代理中固定 Host 标头，使其指向内部上游名称，并将该名称原样填入 MCP_ALLOWED_HOSTS。这样，检查就不依赖公共域名，即使域名更改也能正常工作。 （感谢 @WinFuture23 提供此提示。）
• **/health 会经过 Host 检查，**但不经过令牌检查，因此平台健康检查无需令牌。该端点始终额外接受 localhost、127.0.0.1 和 [::1]，因此即使将 MCP_ALLOWED_HOSTS 固定为公共主机名，捆绑的 Dockerfile 中的 HEALTHCHECK 也能正常工作。如果平台从其他位置通过 HTTP 探测，该平台的主机名必须在列表中：Railway 会发送 Host: healthcheck.railway.app。

完整政策以及漏洞报告方式，请参阅 SECURITY.md。

致谢与许可证

这是面向 LearnWorlds 的非官方社区集成；与 LearnWorlds 无关联，也未获其认可。基于 Model Context Protocol 构建。根据 MIT License 授权。