Moodle Connector

Moodle REST API client, batch downloader, and MCP server for Claude Code integration. SSO-enabled with support for Azure AD, Google, and SAML.

Enterprise-ready Moodle REST API client with SSO authentication, batch downloading, and MCP protocol support for Claude Code and OpenCode.

Features

Complete Moodle API Access

• List courses, check grades, track assignments
• Fetch materials, deadlines, announcements
• Download files with aggressive caching

🆕 Enterprise SSO Support (v2.0.0)

• Azure AD / Entra ID — Full OAuth2 integration
• Google OAuth — Google Workspace and personal accounts
• SAML — Generic SAML provider support
• Mobile Launch Flow — Seamless SSO for mobile apps
• Token rotation and automatic refresh

Multiple Integration Modes

• CLI: python moodle_connector.py courses
• Python Library: from moodle_connector import MoodleConnector
• MCP Protocol: Native integration with Claude Code, OpenCode
• Headless Mode — Tampermonkey helper for CI/CD and automation

Generic Batch Downloader

• JSON-driven configuration (zero code modification)
• Works with any Moodle module
• Auto-organized by course name

Security

• Encrypted credentials (PBKDF2 + Fernet)
• Token management built-in
• No secrets in git history
• MIT licensed
• Safe for headless environments (CI/CD compatible)

Installation

Once installed via clawhub install moodle-connector:

cd ./skills/moodle-connector
pip install -r requirements.txt
playwright install chromium

Quick Start

1. Setup Moodle Token

cp config.template.json config.json
# Edit config.json with your Moodle web service token

2. Use CLI

python moodle_connector.py courses        # List all courses
python moodle_connector.py grades         # Check grades
python moodle_connector.py assignments    # View assignments
python moodle_connector.py materials --course-id 44864
python moodle_connector.py download "https://mytimes.taylors.edu.my/..." --output myfile.pdf
python moodle_connector.py summary        # Full markdown export

🆕 SSO Authentication (v2.0.0)

Azure AD / Entra ID

# Set environment variables
export MOODLE_SSO_PROVIDER="azure"
export MOODLE_SSO_TENANT_ID="your-tenant-id"
export MOODLE_SSO_CLIENT_ID="your-client-id"
export MOODLE_SSO_CLIENT_SECRET="your-client-secret"

# Run with SSO
python moodle_connector.py courses
# Browser opens automatically for login

Google OAuth

export MOODLE_SSO_PROVIDER="google"
export MOODLE_SSO_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export MOODLE_SSO_CLIENT_SECRET="your-client-secret"

python moodle_connector.py courses

SAML Provider

export MOODLE_SSO_PROVIDER="saml"
export MOODLE_SSO_IDP_URL="https://your-idp.example.com"
export MOODLE_SSO_ENTITY_ID="your-moodle-entity-id"

python moodle_connector.py courses

Headless/CI-CD Deployment

Use Tampermonkey helper script for automated workflows:

export MOODLE_HEADLESS=true
export MOODLE_SSO_PROVIDER="azure"
# Token is saved to config.json automatically

# Run in CI/CD
python moodle_connector.py summary > report.md

3. Use Python Library

from moodle_connector import MoodleConnector
from pathlib import Path

connector = MoodleConnector(
    config_path=Path('config.json'),
    password='encryption-password'
)

courses = connector.courses()
grades = connector.grades()
assignments = connector.assignments()
materials = connector.materials()
deadlines = connector.deadlines()
announcements = connector.announcements()
content = connector.summary()

# Download with caching
file_content = connector.download("https://...")

4. Batch Download (Any Module)

cp downloads.example.json downloads.json
# Edit downloads.json to add modules and file URLs
python batch_downloader.py

Output Structure:

downloads/
├── Your_Module_Name_1/
│   ├── file1.pdf
│   ├── file2.zip
│   └── ...
└── Your_Module_Name_2/
    ├── lecture.pdf
    └── ...

MCP Integration (Claude Code / OpenCode)

REQUIRED: Set MOODLE_CRED_PASSWORD environment variable before starting Claude Code.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "moodle-connector": {
      "command": "python",
      "args": ["./skills/moodle-connector/mcp_server.py"],
      "env": {
        "MOODLE_CRED_PASSWORD": "your-encryption-password"
      }
    }
  }
}

Important: Replace your-encryption-password with your actual encryption password used in config.json.

Restart Claude Code. All 8 Moodle functions are now available as native MCP tools:

• courses() — List enrolled courses
• grades() — Get grades
• assignments() — Get assignments
• materials() — Get course materials
• deadlines() — Get upcoming deadlines
• announcements() — Get course news
• download(url, output?) — Download files
• summary() — Get complete data export

Configuration

Moodle Token (config.json)

{
  "moodle": {
    "base_url": "https://mytimes.taylors.edu.my",
    "web_service_token": "YOUR_TOKEN_HERE"
  },
  "cache": {
    "api_ttl_seconds": 300
  }
}

Batch Downloader (downloads.json)

{
  "downloads": [
    {
      "module": "Machine Learning",
      "course_id": 44864,
      "files": [
        {
          "name": "Week1.zip",
          "url": "https://mytimes.taylors.edu.my/webservice/pluginfile.php/..."
        }
      ]
    }
  ]
}

Requirements

• Python 3.10+
• requests ≥2.31.0
• cryptography ≥41.0.0
• playwright ≥1.40.0
• mcp ≥0.1.0 (for MCP server)

Supported Moodle Instances

Tested with:

• Taylor's University (mytimes.taylors.edu.my)
• Should work with any Moodle 3.x+ instance

Security Notes

• Environment-enforced: MOODLE_CRED_PASSWORD is required — no hardcoded defaults
• Error sanitization: MCP server sanitizes errors, no internal details leaked to clients
• Encrypted credentials: PBKDF2 (480K iterations) + Fernet encryption
• Safe for headless: Use MOODLE_CRED_PASSWORD env var for automation
• Git-safe: Never commit config.json with real tokens
• No telemetry: No external data transmission or logging

Troubleshooting

"Invalid parameter value detected" for calendar API

Use assignments() instead — gets same deadline info.

Browser MFA not triggering

Run: python moodle_connector.py login for manual token retrieval.

File download stuck

Check network. Increase timeout in code or clear cache: rm -rf cache/

License

MIT — See LICENSE file for details. You are free to use, modify, and distribute this software.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request
4. Agree to license your work under GPLv3

Author

Jabir Iliyas Suraj-Deen

• GitHub: https://github.com/Jabir-Srj
• Email: [e-mail]
• Taylor's University, Kuala Lumpur, Malaysia

---

GitHub: https://github.com/Jabir-Srj/moodle-connector Release: v2.0.0 (March 30, 2026)

What's New in v2.0.0

✨ Enterprise SSO Support

• Azure AD, Google OAuth, and SAML authentication
• Mobile Launch Flow integration
• Headless deployment with Tampermonkey support
• Bilingual documentation (English & Spanish)
• Enhanced security with token rotation