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をそのまま転送するだけのMCPサーバーもあります。このサーバーは、LLMに安心して任せられ、実運用しやすいように設計されています。

得られるもの	重要な理由
仕様に基づく全94エンドポイント	コース、ユーザー、登録、支払い、サブスクリプション、クーポン、証明書、座席、コミュニティ、レポートをすべて網羅しています。選別した一部だけに限らず、取りこぼしもありません。
すべてのツールを安全性別に分類 🟢 / 🟡 / 🔴	各ツールの説明の先頭にあるバナーで、モデルは実行前に、そのツールが読み取り、作成、更新、削除のどれを行うかを正確に把握できます。
人間ではなくエージェント向けに書かれた説明	すべてのツールの説明に、副作用、認証とレート制限の動作、戻り値の形式、エラーコード、使用すべきでない場面、代替となる関連ツールが明記されています。
機械可読なMCPアノテーション（readOnlyHint、destructiveHint）	アノテーションに対応したホスト（Claudeなど）は、読み取りを自動的に信頼し、破壊的な操作の前に確認を求めることができます。
バックオフ付きの自動リトライ	一時的な429／5xxレスポンスに対し、ジッター付き指数バックオフでリトライし、サーバーのRetry-Afterヘッダーにも従います。
組み込みのレート制限	LearnWorldsの10秒あたり30リクエストという上限を超えないよう自動的にリクエストを調整するため、ツール呼び出しが集中しても429が発生しません。
リクエストごとのタイムアウト	上流の呼び出しが応答しなくなった場合は中断してリトライするため、サーバーがフリーズしません。
stdioとStreamable HTTPの2種類のトランスポート	Claude Desktopでローカルに使うことも、常時稼働するサーバーを起動して任意の数のMCPクライアントからHTTP経由でアクセスすることもできます。
Docker、docker-compose、ヘルスチェック、自動再起動	本番環境を想定したデプロイをすぐに利用できます。docker compose upを実行すれば、稼働し続けます。
HTTPエンドポイントでのベアラートークン認証	サーバーをループバックアドレス以外にバインドする場合は必須です。MCP_AUTH_TOKENが設定されていない場合、APIを保護せずに公開することなく、起動を拒否します。
シークレットがモデルに渡ることはありません	認証情報はサーバーの環境内に保持され、リクエストごとに注入されます。アシスタントが目にするのは、ツールの入力とAPIレスポンスだけです。
仕様を差し替えるだけで更新可能	LearnWorldsから新しいYAMLが公開された場合は、ファイルを1つ置き換えて再ビルドするだけです。コードを変更せずに、新しいエンドポイントが自動的に新しいツールになります。

他の方法との比較

執筆時点では、LearnWorlds専用のMCPサーバーはこれだけのようです。 代わりに、汎用のOpenAPI→MCPラッパーに仕様を渡す方法もありますが、次の機能は利用できません。

機能	このプロジェクト	汎用OpenAPI→MCPラッパー*
LearnWorldsの全94エンドポイントをツールとして利用	✅	✅
ツールごとの🟢／🟡／🔴安全性分類とバナー	✅	❌
readOnlyHint／destructiveHint MCPアノテーション	✅	➖
$refの解決と再帰に安全なスキーマ	✅	➖
429／5xxの自動リトライ（Retry-Afterに準拠）	✅	❌
クライアント側のレート制限（10秒あたり30リクエスト未満を維持）	✅	❌
中断可能なリクエストごとのタイムアウト	✅	➖
stdioトランスポート	✅	✅
Streamable-HTTPトランスポート	✅	➖
Docker、docker-compose、ヘルスチェック、自動再起動	✅	❌
エンドポイントでのベアラートークン認証の強制	✅	❌
認証情報をサーバー側で注入し、モデルには送信しない	✅	➖
ライセンス	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 の解決と再帰スキーマへの対策を行います）、各ツールに安全性のカテゴリを付与して、すべての送信リクエストにベアラートークンと Lw-Client ヘッダーを挿入します。認証情報はサーバーの環境内に保持され、モデルが認証情報を見たり扱ったりすることはありません。

要件

• API アクセスが有効な LearnWorlds スクール — アクセストークンとクライアント ID（admin → Settings → Integrations → Developers）、およびスクールの 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 を指定してカスタムコネクター（Settings → Connectors）を追加するか、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 — 次のコマンドを1つ実行します。

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

• Claude Cowork — Claude Code の MCP 設定を共有するため、上記のコマンドを実行すると、そちらでもツールを利用できるようになります。

ビルド済みイメージを使用しますか？

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. Settings → Integrations → Developers（API 画面）に移動します。
3. Access Token をコピーして LEARNWORLDS_API_TOKEN に、Client ID をコピーして LEARNWORLDS_CLIENT_ID に設定します。
4. LEARNWORLDS_BASE_URL に、スクールの API ベース URL を設定します。 https://<your-school>.learnworlds.com/admin/api を指定してください。スクールでカスタムドメインを使用している場合は、代わりにそのホストを使用します（例：https://academy.example.com/admin/api）。

3つすべてを .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	⚠️	(オフ)	/mcp で Authorization: Bearer <token> を必須にします。HOST がループバックアドレスではない場合は必須です。設定されていないと、サーバーは起動を拒否します。1.1.0 で MCP_SHARED_TOKEN から名称が変更されました
MCP_ALLOWED_HOSTS	—	(自動)	Host ヘッダーで許可するホスト名をカンマ区切りで指定します（DNS リバインディング対策）。リバースプロキシの背後で必要です
MCP_ALLOW_INSECURE	—	(オフ)	起動拒否を解除します。ほかの誰もアクセスできないエンドポイントでのみ使用してください
MCP_SESSION_TTL	—	1800	セッションが破棄されるまでのアイドル秒数
MCP_MAX_SESSIONS	—	256	同時セッションの最大数
MCP_BODY_LIMIT	—	25mb	受け付けるリクエストボディの最大サイズ
LEARNWORLDS_MAX_REQUESTS	—	25	クライアント側の時間枠ごとのリクエスト数（0 でスロットリングを無効化）
LEARNWORLDS_RATE_WINDOW_MS	—	10000	レート制限の時間枠（ミリ秒）
LEARNWORLDS_MAX_RETRIES	—	3	429／5xx／ネットワークエラー発生時の再試行回数
LEARNWORLDS_TIMEOUT_MS	—	30000	試行ごとのリクエストタイムアウト
LEARNWORLDS_OPENAPI_PATH	—	(同梱)	別の 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 ツールを自動的に信頼できます。

バナーの下にある説明はすべて同じ構成に従っているため、エージェントは探りを入れずに、最初に説明を読んだだけで操作できます。

行	説明する内容
(目的)	エンドポイントの役割を、OpenAPI 仕様からそのまま一度だけ示します。
動作	呼び出しが稼働中のスクールに与える影響、冪等性の有無、認証、スロットリング、再試行の処理方法を説明します。
パラメーター	入力スキーマでは示せない内容のみを説明します。body ラッパー、ページネーション、名前が変更された引数が対象です。
戻り値	HTTP <status> と JSON の結果形式、および返される可能性のあるエラーコードを説明します。
使用する場面	使用する場面、使用しない場面、および同じ分野の関連ツールを最大 5 つ紹介します。

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 のリストレスポンスはページ分割されます（通常、1 ページあたり 20～50 件）。
• レート制限：LearnWorlds では 10 秒あたり 30 リクエストまで許可されています。サーバーは LEARNWORLDS_RATE_WINDOW_MS あたり LEARNWORLDS_MAX_REQUESTS 件（デフォルトでは 10 秒あたり 25 件）に自己スロットリングし、それでも受信した 429 は再試行します。
• リクエストボディ：書き込みツールは body 引数を受け取ります。そのスキーマは仕様から解決され、モデルに表示されます。

セキュリティ

• API の認証情報は .env にのみ保存されます。このファイルは git の追跡対象外です。実際のシークレットを絶対にコミットしないでください。 トークンが漏えいした場合は、LearnWorlds admin → Settings → Integrations → Developers (API) でローテーションしてください。
• HTTP エンドポイントをループバック以外にバインドすると、トークンが必須になります。 MCP_AUTH_TOKEN が設定されていない場合、サーバーは起動を拒否し、必要な対応を説明するエラーを表示します。TLS の背後で、Authorization: Bearer <token> ヘッダーとして送信してください。
• localhost でも同様です：トークンが設定されていない場合、Host ヘッダーは localhost の名前に制限されるため、DNS リバインディングを使って Web ページからエンドポイントにアクセスすることはできません。ループバックへのバインドだけでは保護になりません。リバースプロキシの背後では、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 の下でライセンスされています。