moodle-mcp-server — AI 기반 LMS 분석

Moodle 인스턴스에 무엇이든 물어보세요. 몇 초 만에 구조화된 답변을 얻을 수 있습니다.

moodle-mcp-server는 AI 에이전트를 Moodle의 웹 서비스 API에 직접 연결하는 오픈 소스 MCP(Model Context Protocol) 서버입니다. CSMediaPro의 더 광범위한 AQL(Agentic Query Layer) 작업을 뒷받침하는 Moodle 커넥터입니다.

리포트 빌더를 배우거나, SQL을 작성하거나, CSV를 내보내는 대신, 일반 영어로 질문하면 AI 에이전트가 LMS를 쿼리하여 구조화된 데이터를 반환합니다.

프로젝트 홈페이지: https://csmediapro.com/products/moodle-mcp-server npm 패키지: https://www.npmjs.com/package/moodle-mcp-server-aql MCP 레지스트리: io.github.csmediapro/moodle-mcp-server-aql

기능

• 핵심 쿼리 도구 — 강좌 카탈로그, 사용자 등록, 과제, 카테고리 탐색, 사이트 메타데이터, 사용자 조회, 캐시 관리

• 프리미엄 리포트 플러그인 — 강좌 완료 보고서 및 최근 활동과 같은 선택적 도구를 플러그인 런타임을 통해 연결 가능

• LLM 비종속적 — Claude, GPT, Gemini, Ollama 또는 모든 MCP 호환 AI 클라이언트와 작동

• LMS 수정 불필요 — Moodle의 기존 웹 서비스 API 사용, 플러그인 설치 불필요

• 규정 준수 가능 데이터 처리 — 보안 및 효율적인 데이터 처리, 설계에 의한 프라이버시(privacy by design)

• 읽기 전용 — Moodle 데이터를 절대 수정하지 않으며, 프로덕션 환경에서 안전

• 플러그인 확장 가능 — 새로운 도구 모듈을 디렉토리에 추가하기만 하면 됨; 도구 및 선택적 에이전트 라우팅 힌트가 런타임에 자동 등록

Related MCP server: Moodle MCP Server

빠른 시작

필수 조건

• Node.js 20+

• 웹 서비스가 활성화된 Moodle 인스턴스

• Moodle API 토큰 (사이트 관리 → 플러그인 → 웹 서비스 → 토큰 관리)

MCP 클라이언트와 함께 사용하기

대부분의 사용자는 Claude Desktop과 같은 MCP 클라이언트를 통해 서버를 실행합니다:

{
  "mcpServers": {
    "moodle-mcp-server-aql": {
      "command": "npx",
      "args": ["-y", "moodle-mcp-server-aql"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.example",
        "MOODLE_TOKEN": "your-moodle-web-services-token"
      }
    }
  }
}

소스에서 설정하기

# Clone the repo
git clone https://github.com/csmediapro/moodle-mcp-server
cd moodle-mcp-server

# Install dependencies
npm install

# Configure
cp packages/server/.env.example packages/server/.env
# Edit .env: add your MOODLE_URL and MOODLE_TOKEN

# Run (stdio mode)
npm run server:build
node packages/server/dist/index.js

사용자 필드 스키마

사용자 필드 표시 설정은 Moodle 인스턴스별로 생성되며 로컬에 저장됩니다: packages/server/data/user-field-schema.json. 이 파일은 사이트별 사용자 정의 프로필 필드를 포함할 수 있으므로 의도적으로 git에서 무시됩니다.

Moodle 사이트에 연결한 후 refresh_user_field_schema 도구를 한 번 실행하여 사용 가능한 표준 및 사용자 정의 사용자 필드를 발견하세요. 최소 예제 형태는 packages/server/data/user-field-schema.example.json에 포함되어 있습니다.

user-directory 플러그인은 사용자 정의 프로필 필드를 school과 같은 최상위 키로 평탄화한 정규화된 전체 사용자 캐시를 저장합니다. 해당 캐시가 존재하면 list_users는 캐시된 사용자를 메모리에서 필터링할 수 있고, summarize_user_directory_field는 캐시된 고유 값과 개수를 반환할 수 있습니다. 예를 들어 "고유 학교 표시" 또는 "학교 및 각 학교에 할당된 사용자 수 표시"는 다른 Moodle 가져오기 없이 캐시된 school 필드를 요약합니다.

구성 ID

코어는 두 가지 다른 서버 ID 필드를 소유합니다:

• server.id — 안정적인 머신 ID, 예: mcp_8f3k2q9x

• server.name — 사람이 보는 표시 레이블

server.id가 없으면 코어가 한 번 생성하여 시작이 계속되기 전에 해결된 구성 파일에 저장합니다.

환경 변수 재정의:

• MOODLE_MCP_CONFIG 또는 MOODLE_MCP_SERVER_CONFIG — 구성 파일 경로 선택

• SERVER_ID — 명시적 server.id 재정의

• SERVER_NAME — 명시적 server.name 재정의

• SERVER_VERSION — 명시적 server.version 재정의

server.id가 없고 해결된 구성 경로에 쓸 수 없으면 시작이 의도적으로 실패합니다.

참조 클라이언트 사용하기

# From the project root
cp packages/client/.env.example packages/client/.env
npm run client:dev
# Open http://localhost:3000

클라이언트가 자동으로 Moodle 인스턴스를 감지하고 일반 영어로 질문할 수 있는 채팅 인터페이스를 제공합니다.

LLM 연결하기

moodle-mcp-server는 자연어 인터페이스를 구동할 AI 모델이 필요합니다. 모델은 사용자가 가져옵니다 — moodle-mcp-server 코어와 참조 클라이언트는 모든 MCP 호환 제공자를 지원합니다.

옵션 1: 로컬에서 실행 (속도 및 개인정보 보호에 권장)

로컬 모델을 실행하면 모든 데이터가 사용자 하드웨어에 머무르며 네트워크를 벗어나지 않습니다. 최신 양자화된 모델은 소비자 GPU 및 CPU 전용 설정에서도 잘 작동합니다.

성능: 단일 RTX 3090에서 양자화된 24B 모델은 첫 번째 쿼리 후 약 1.5초의 응답 시간을 제공합니다 — 시스템이 초기화되면 대부분의 클라우드 API보다 빠릅니다.

Ollama를 통한 방법 (가장 쉬움)

# Install Ollama: https://ollama.com
ollama pull gemma3:12b      # Fast, reliable tool use (~200ms TTFT)
ollama pull qwen3:14b       # Strong reasoning, good for complex queries
ollama pull deepseek-r1:14b # Excellent at multi-step chains

그런 다음 참조 클라이언트를 http://localhost:11434 (Ollama 기본값)로 지정합니다.

llama.cpp를 통한 방법 (최대 제어)

# Download a GGUF model (example: Devstral 24B Q4)
# Run the llama.cpp server:
llama-server -m devstral-24b-Q4_K_M.gguf --ctx-size 60000 --port 8080

참조 클라이언트를 http://localhost:8080/v1로 지정합니다.

권장 로컬 모델

옵션 2: 클라우드 제공자

Anthropic (Claude):

export ANTHROPIC_API_KEY=sk-ant-...

참조 클라이언트의 제공자 드롭다운에서 "Anthropic"을 선택하세요. Claude Sonnet이 가장 안정적인 도구 호출 동작을 제공합니다.

OpenAI (GPT):

export OPENAI_API_KEY=sk-...

제공자 드롭다운에서 "OpenAI"를 선택하세요. GPT-4o는 구조화된 쿼리에서 우수한 성능을 보입니다.

Ollama Cloud: 로컬 Ollama와 동일한 API를 사용하며, https://ollama.com/v1에서 호스팅됩니다. 좋은 중간 지점 — 로컬 콜드 스타트보다 빠르고, 대형 클라우드 제공자보다 더 비공개적입니다.

옵션 3: Claude Desktop (직접 MCP)

Claude Desktop은 참조 클라이언트 없이 moodle-mcp-server 코어에 stdio로 직접 연결됩니다.

Claude Desktop 구성(claude_desktop_config.json)에 추가:

{
  "mcpServers": {
    "moodle-mcp-server": {
      "command": "node",
      "args": ["/path/to/moodle-mcp-server/packages/server/dist/index.js"],
      "env": {
        "MOODLE_URL": "https://your-moodle-instance.com",
        "MOODLE_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Desktop을 다시 시작하세요. 서버의 도구가 Claude의 도구 목록에 나타납니다 — 질문을 직접 하세요.

도구

핵심 도구 (무료, 오픈 소스 — AGPL)

프리미엄 플러그인 (별도 구매 가능)

• 고급 보고 — 성적부, 강좌 간 비교, 사용자 정의 보고서 빌더

• 사용자 분석 — 진행 추적, 참여 점수, 위험 플래그

• 사용자 디렉토리 — 표준 및 사용자 정의 프로필 필드 전체에 걸친 캐시된 디렉토리 목록 및 구조화된 필터링

• 규정 준수 팩 — 인증 추적, 만료 알림, 감사 내보내기

아키텍처

User (plain English question)
    │
    ▼
AI Agent (Claude / GPT / Gemini / Ollama / local)
    │
    ▼  MCP Protocol
`moodle-mcp-server`
    ├── Tool Registry (core + plugins)
    ├── Agent Runtime Config (core + plugin rules)
    ├── Optimized Data Layer (secure, efficient data handling)
    └── Moodle Client (REST API calls)
    │
    ▼
Moodle Web Services API

전송 모드

• Stdio — dist/index.js — 서브프로세스로 실행되며, Claude Desktop 및 유사한 클라이언트에서 사용

OSS 코어는 의도적으로 stdio만 제공합니다. 네트워크 연결 래퍼, 원격 감독 또는 프리미엄 플러그인 연결은 별도의 상업용 노드 에이전트 또는 래퍼에 속합니다.

플러그인 문서

• 플러그인 계약

• 플러그인 생성하기

• Hello 플러그인 예제

라이선스

AGPL v3 — LICENSE 참조.

이는 다음을 의미합니다:

• ✅ 모든 환경에서 moodle-mcp-server 코어를 무료로 사용할 수 있습니다.

• ✅ 필요에 따라 소스 코드를 수정할 수 있습니다.

• ✅ 파생 작업을 빌드하고 배포할 수 있습니다.

다음은 할 수 없습니다:

• ❌ moodle-mcp-server 코어를 폐쇄 소스 경쟁 상업 제품으로 재패키징할 수 없습니다.

• ❌ 수정 사항을 공유하지 않고 네트워크 서비스로 제공할 수 없습니다.

상표 고지

Moodle은 Moodle Pty Ltd의 상표입니다. moodle-mcp-server는 독립적인 CSMediaPro 프로젝트이며 Moodle Pty Ltd 또는 Moodle 프로젝트와 제휴, 승인, 후원 또는 공식적으로 연결되어 있지 않습니다. 이 이름은 Moodle LMS와의 호환성을 설명하기 위해 사용됩니다.

CSMediaPro 제작

moodle-mcp-server는 AI 통합, 시스템 엔지니어링 및 워크플로 자동화를 전문으로 하는 소프트웨어 개발 회사 CSMediaPro에서 구축 및 유지 관리합니다.

• 연락처: contact@csmediapro.com