Skip to main content
Glama
deenesjakoruzh
MarcosNahuel

moodle-mcp

by MarcosNahuel
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

moodle-mcp

Moodle을 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. AI 에이전트가 웹 서비스를 통해 Moodle에서 수업, 리소스, 활동과 같은 교육 콘텐츠를 게시하고 관리할 수 있도록 하며, 멱등성을 보장합니다.

CI npm license: MIT

상태: v0.1 MVP.

개요

moodle-mcp는 표준 입출력(stdio) 기반의 MCP 서버로, 소규모의 고수준 **파사드(facades)**와 하나의 저수준 ws_raw 기본 요소를 제공하여 정형화된 교육용 "Ficha"(YAML 프론트매터가 포함된 마크다운 파일)를 Moodle 코스에 실제 섹션, 페이지, 리소스 및 활동으로 게시합니다. 모든 쓰기 작업은 idnumber를 기준으로 업서트(upsert)되므로, 동일한 Ficha를 다시 게시해도 중복이 생성되지 않습니다.

주요 소비자: Italicia 언어 교육 워크플로우를 구동하는 Claude Desktop. 하지만 이는 범용 오픈 소스 어댑터이므로, 웹 서비스가 활성화된 Moodle 4.x/5.x 인스턴스와 MCP 호환 에이전트라면 무엇이든 사용할 수 있습니다.

v0.1에서 제공되는 도구

도구

목적

obtener_contexto_curso

코스 스냅샷: 메타데이터, 섹션, 최근 MCP로 게시된 수업, 등록 수.

publicar_ficha_clase

FichaClase(절대 마크다운 경로)를 Moodle 섹션 + 모듈 업데이트로 게시.

publicar_preview

위와 동일하지만 강제로 숨김 처리 + 미리보기 URL 반환.

confirmar_preview

이전에 숨겨진 섹션과 해당 모듈을 학생들에게 공개.

ws_raw

탈출구: 모든 Moodle WS 함수를 직접 호출.

v0.1에는 포함되지 않음(v0.2+ 계획): publicar_ficha_examen, sync_alumnos_csv, HTTP/SSE 전송, GIFT 빌더, 멀티파트 에셋 업로드, 자동 모듈 생성.

설치

# Via npx (recommended for Claude Desktop)
npx -y @marcosnahuel/moodle-mcp

# Or install globally
npm install -g @marcosnahuel/moodle-mcp

Node.js 20 이상이 필요합니다.

구성 (환경 변수)

변수

필수

기본값

설명

MOODLE_URL

예

—

Moodle 인스턴스의 전체 HTTPS URL.

MOODLE_WS_TOKEN

예

—

편집 권한이 있는 웹 서비스 토큰.

MOODLE_WS_TIMEOUT_MS

아니오

30000

요청당 타임아웃.

MOODLE_WS_MAX_RETRIES

아니오

3

일시적 오류 발생 시 재시도 횟수.

MOODLE_WS_RATE_LIMIT_PER_SEC

아니오

10

토큰 버킷 속도 제한.

MCP_LOG_LEVEL

아니오

info

error / warn / info / debug.

MOODLE_ALLOW_INSECURE

아니오

false

http:// URL 허용 (개발 전용 탈출구).

Claude Desktop 구성

claude_desktop_config.json에 추가하십시오 (OS별 정확한 경로는 examples/setup-claude-desktop.md 참조):

{
  "mcpServers": {
    "moodle": {
      "command": "npx",
      "args": ["-y", "moodle-mcp"],
      "env": {
        "MOODLE_URL": "https://your-moodle.example.com",
        "MOODLE_WS_TOKEN": "your-ws-token"
      }
    }
  }
}

Claude Desktop을 재시작하십시오. 이제 위의 5가지 도구를 에이전트가 사용할 수 있습니다.

예시

1. 작업 전 코스 스냅샷 찍기

// tool call
{
  "name": "obtener_contexto_curso",
  "arguments": { "course_id": 42, "incluir_ultimas_clases": 5 }
}

응답 (요약):

{
  "course": { "id": 42, "fullname": "Italiano A1", "shortname": "ITA-A1", "format": "topics", "startdate": 1700000000 },
  "secciones": [{ "id": 100, "name": "Unidad 3", "section": 3, "visible": true, "modules_count": 6 }],
  "ultimas_clases": [{ "seccion_id": 100, "seccion_name": "Unidad 3", "ficha_idnumber": "mcp:a9993e364706816aba3e2571" }],
  "matriculados": { "total": 18, "docentes": 1, "alumnos": 17 }
}

2. FichaClase 게시 (먼저 미리보기)

{
  "name": "publicar_preview",
  "arguments": {
    "ficha_path": "/home/alicia/fichas/italiano/a1-2026/u3/c5.md",
    "course_id": 42
  }
}

응답에는 Alicia가 검토할 수 있는 preview_url이 포함됩니다. 승인 후:

{
  "name": "confirmar_preview",
  "arguments": { "seccion_id": 100, "recursos_ids": [501, 502, 503] }
}

3. 탈출구 — 원시 WS 함수 호출

{
  "name": "ws_raw",
  "arguments": {
    "function_name": "core_webservice_get_site_info",
    "params": {}
  }
}

응답:

{ "data": { "sitename": "Aula Italicia", "release": "5.0.2+", ... } }

멱등성

이 MCP에 의해 생성된 모든 리소스는 다음과 같은 형식의 안정적인 idnumber를 가집니다:

mcp:<first 24 chars of sha1(ficha.id + "|" + component_id)>

동일한 Ficha를 다시 게시하면 idnumber를 통해 기존 리소스를 찾아 제자리에서 업데이트합니다. 중복이 생성되지 않습니다. 언제 어디서나 안전하게 재시도할 수 있습니다.

v0.1 주의사항

v0.1은 기능적 한계를 명확히 합니다. 다음은 안정적으로 수행됩니다:

  • 코스, 섹션 및 모듈 조회.

  • mcp: idnumber 접두사를 가진 "소유" 리소스 찾기.

  • 기존 모듈의 공개 여부 업데이트 (미리보기 → 확인 워크플로우).

  • 안정적인 code 필드가 포함된 구조화된 Moodle 오류 표시.

  • 토큰을 절대 기록하지 않으며, 스택 추적을 전파하지 않음.

v0.1은 아직 다음을 수행하지 않습니다:

  • 멀티파트를 통해 Moodle 임시 파일 영역으로 에셋 파일 업로드. 에셋 업로드를 위해 계획된 호출은 advertencias로 보고되므로, 처음에는 수동으로 시드하십시오.

  • 웹 서비스를 통해 완전히 새로운 섹션이나 모듈 생성. 모듈이 아직 존재하지 않는 경우, 도구는 "missing" 상태와 advertencia를 반환합니다. local_wsmanagesections(또는 동등한 것)를 설치하고 해당 엔드포인트를 연결하는 것은 v0.2 작업입니다.

두 가지 격차 모두 실제 Moodle 도커 환경에서 실행될 때 tests/integration/의 통합 제품군에 의해 해결됩니다.

개발

git clone https://github.com/marcosnahuel/moodle-mcp
cd moodle-mcp
npm install

npm run typecheck         # tsc --noEmit
npm test                  # vitest unit suite
npm run test:coverage     # with v8 coverage (≥80% enforced)
npm run build             # tsup → dist/

# Integration — requires docker
docker compose -f tests/integration/docker-compose.test.yml up -d
export MOODLE_TEST_URL=http://localhost:8081
export MOODLE_TEST_TOKEN=<generate in Moodle admin>
export MOODLE_TEST_COURSE=<course id>
npm run test:integration
docker compose -f tests/integration/docker-compose.test.yml down -v

보안

  • 토큰은 절대 기록되지 않습니다. 로그 레코드의 모든 필드에 나타나는 토큰은 ***로 대체됩니다.

  • 오류 메시지의 URL도 마찬가지로 수정됩니다.

  • MOODLE_ALLOW_INSECURE=true(개발 전용)가 아닌 경우 HTTPS가 필수입니다.

  • MCP는 웹 서비스 REST를 통해서만 Moodle과 통신합니다. 쿠키 인증, 웹 스크래핑, 직접적인 DB 액세스는 없습니다.

기여

이슈, PR 및 커밋 규칙은 CONTRIBUTING.md를 참조하십시오.

이 프로젝트에 참여함으로써 귀하는 CODE_OF_CONDUCT.md를 준수할 것에 동의하게 됩니다.

라이선스

MIT © 2026 Italicia — LICENSE 참조.

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - A tier

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/MarcosNahuel/moodle-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server