moodle-study-kit 0.1.0

Read-only Moodle toolkit for agents, MCP servers, and local scripts

moodle-study-kit

Read-only Moodle toolkit for students and agents. Provides a Python library, CLI, and MCP server for accessing Moodle course data without any write operations.

Quick start

# Clone and install
git clone <repo-url> && cd moodle-study-kit
python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'

Windows note: If moodle-study is not recognised after installation, the Python Scripts folder isn't on your PATH. Either:

1. Add it manually — find the path with:

   py -c "import site; print(site.getUserSitePackages())"
   

   Then add it to your PATH in Windows Settings > System > Environment Variables.

2. OR use the module form as a workaround (works immediately, no PATH needed):

   py -m moodle_study_kit.cli courses
   

# Run guided setup
moodle-study setup

The setup command will prompt for your Moodle URL, API token, and user ID, then verify the connection and save credentials to ~/.config/moodle-study-kit/config.json.

Getting a Moodle API token

1. Log in to your Moodle site in a browser.
2. Go to Site administration > Plugins > Web services > Manage tokens, or ask your Moodle admin for a web-service token.
3. If your institution uses the Moodle mobile app, you may already have a token. Check your Moodle mobile app settings or use the Moodle mobile web-service endpoint:

   https://<your-moodle>/login/token.php?username=YOUR_USER&password=YOUR_PASS&service=moodle_mobile_app
   

   Note: Only use this over HTTPS. Never share your token.
4. Copy the token for use in setup.

Configuration

Credentials are resolved in this order:

1. Explicit arguments passed to MoodleConfig.load(url=..., token=...)
2. Environment variables: MOODLE_URL, MOODLE_TOKEN, MOODLE_USERID
3. Config file (first found):
   • $MOODLE_CREDS_PATH (if set)
   • ~/.config/moodle-study-kit/config.json
   • ~/.moodle_creds.json

Config file format

{
  "url": "https://moodle.example.ac.uk",
  "token": "your_token_here",
  "userid": 12345
}

Environment variables

export MOODLE_URL="https://moodle.example.ac.uk"
export MOODLE_TOKEN="your_token_here"
export MOODLE_USERID="12345"

CLI usage

moodle-study courses              # List enrolled courses
moodle-study deadlines            # Show upcoming deadlines (14-day window)
moodle-study deadlines --days 7   # Shorter look-ahead
moodle-study contents 12345       # Show sections for course ID 12345
moodle-study contents EC100       # Look up by course short-code
moodle-study contents MG488       # Prefix match: finds MG488_2526 if unique
moodle-study materials EC100      # Discover all downloadable materials
moodle-study materials EC100 --week 3   # Materials for week 3 only
moodle-study setup                # Guided first-time setup

Add --json before the command for machine-readable JSON output:

moodle-study --json courses
moodle-study --json deadlines

MCP server

For use with Claude Code, OpenClaw, or other MCP-capable agents:

pip install -e "moodle-study-kit[mcp]"
python -m moodle_study_kit.mcp_server

The server runs as a stdio-based MCP server. Tools: list_courses, get_deadlines, get_course_contents, get_week_materials, search_course_content, get_weekly_summary.

Claude Code: Add to your Claude Code settings / MCP Servers config:

{
  "mcpServers": {
    "moodle-study-kit": {
      "command": "python",
      "args": ["-m", "moodle_study_kit.mcp_server"]
    }
  }
}

Set MOODLE_URL, MOODLE_TOKEN, MOODLE_USERID as environment variables or in ~/.config/moodle-study-kit/config.json.

OpenClaw: Add to your agent or gateway config:

mcpServers:
  moodle:
    command: python
    args: ["-m", "moodle_study_kit.mcp_server"]
    env:
      MOODLE_URL: "https://your-moodle.example.ac.uk"
      MOODLE_TOKEN: "your_token_here"
      MOODLE_USERID: "12345"

Running tests

pip install -e '.[dev]'
pytest

# On Windows, if pytest isn't found on PATH:
py -m pytest

Safety

This package is read-only by design. Every Moodle API call is checked against a hardcoded allowlist in ALLOWED_FUNCTIONS inside the client module. Write-like operations — submitting assignments, posting forum replies, uploading files, creating events, deleting content — are blocked with a SafetyError before any network request is made.

• Your token cannot modify anything on Moodle, even accidentally.
• Agents (Claude Code, OpenClaw, etc.) can use these tools safely.
• Treat your Moodle API token like a password: never commit it to git, never share it, use HTTPS only.

Known limitations

• Token portability varies by institution. Some Moodle instances require specific web-service configurations. Check with your Moodle administrator about enabling REST web services.
• Rate limiting. Moodle servers may throttle rapid API calls. The package handles errors gracefully but cannot bypass institutional limits.
• Only Moodle REST API v2 is supported.
• Course discovery by short-code uses prefix matching (e.g. "MG488" matches "MG488_2526") — see CLI usage above.

For Agent Authors

moodle-study-kit is designed to be agent-friendly:

• Zero configuration needed for discovery — call list_courses() with no arguments to explore.
• Self-documenting tool names and clear purpose descriptions.
• Structured output by default — use --json on CLI, or rely on structured dict/JSON from the Python API.
• Graceful degradation with clear error messages when credentials are missing.

Example integration in an agent system prompt:

You have access to moodle-study-kit. First run list_courses() to see available courses, then get_deadlines() to check upcoming work, then explore specific courses with get_course_contents().