spoonbobo/moodle-mcp-server

Moodle MCP Server

A Model Context Protocol (MCP) server implementation that provides tools and resources for interacting with Moodle Learning Management System (LMS) via its Web Services API.

Features

This MCP server provides comprehensive tools for Moodle integration:

Course Management

• get_course: Get detailed information about a specific course
• get_courses: List courses with optional category filtering
• create_course: Create new courses in Moodle
• get_course_enrollments: Get users enrolled in a course
• get_course_assignments: Get assignments from a course
• get_course_forums: Get forums from a course

User Management

• get_user: Get user information by ID, username, or email
• search_users: Search for users by name, username, or email
• enroll_user: Enroll a user in a course with specified role

System Information

• get_site_info: Get general site information and capabilities

Resources

• moodle://course/{course_id} - Course data with web interface links
• moodle://user/{user_id} - User data with web interface links
• moodle://course/{course_id}/enrollments - Course enrollment data
• moodle://course/{course_id}/assignments - Course assignments
• moodle://courses - List of courses

Installation

Prerequisites

• Python 3.10 or higher
• A Moodle instance with Web Services enabled
• A valid Moodle Web Service token

Setup

1. Clone or download this MCP server

2. Install dependencies using UV:

   uv sync
   

   Or using pip:

   pip install -e .
   

Environment Configuration

Set the required environment variables:

# Required
export MOODLE_BASE_URL="http://localhost:8080"
export MOODLE_TOKEN="e6e5019748dd95f7380bc25b1be120ba"

# Optional
export MOODLE_VERIFY_SSL="true"  # Set to "false" for self-signed certificates

Or for PowerShell:

$env:MOODLE_BASE_URL="http://localhost:8080"
$env:MOODLE_TOKEN="e6e5019748dd95f7380bc25b1be120ba"

You can also copy env.example to .env and modify it with your credentials.

Moodle Configuration

1. Enable Web Services in your Moodle site:

   • Go to Administration → Site administration → Advanced features
   • Enable "Enable web services"

2. Create a Web Service Token:

   • Go to Administration → Site administration → Server → Web services → Manage tokens
   • Create a new token for a user with appropriate permissions

3. Configure Web Service Functions (if using restricted tokens):

   • Ensure the following functions are enabled:
     • core_course_get_courses_by_field
     • core_course_get_courses
     • core_course_create_courses
     • core_user_get_users_by_field
     • core_user_get_users
     • core_enrol_get_enrolled_users
     • enrol_manual_enrol_users
     • mod_assign_get_assignments
     • mod_forum_get_forums_by_courses
     • core_webservice_get_site_info

Usage

Running the Server

Using UV:

uv run moodle-mcp-server

Or using Python:

python -m moodle_mcp.main

Or if installed globally:

moodle-mcp-server

Integration with MCP Clients

Add to your MCP client configuration:

{
  "moodle": {
    "command": "moodle-mcp-server",
    "env": {
      "MOODLE_BASE_URL": "http://localhost:8080",
      "MOODLE_TOKEN": "e6e5019748dd95f7380bc25b1be120ba"
    }
  }
}

Example Usage

Get Course Information

# Get course with ID 123
course = await get_course(course_id=123)
print(f"Course: {course['courses'][0]['fullname']}")
print(f"Web URL: {course['courses'][0]['web_url']}")

Search for Users

# Search for users named "John"
users = await search_users(query="John", limit=10)
for user in users['users']:
    print(f"User: {user['fullname']} ({user['email']})")
    print(f"Profile URL: {user['web_url']}")

Get Course Enrollments

# Get enrollments for course 123
enrollments = await get_course_enrollments(course_id=123)
print(f"Total enrolled: {enrollments['total_count']}")
for user in enrollments['enrolled_users']:
    print(f"- {user['fullname']} ({user['email']})")

Create a New Course

# Create a new course
new_course = await create_course(
    fullname="Introduction to Python",
    shortname="PYTHON101",
    category_id=1,
    summary="Learn Python programming basics"
)
print(f"Created course: {new_course[0]['web_url']}")

API Functions

Authentication

All API requests use token-based authentication. The token is automatically included in all requests using the MOODLE_TOKEN environment variable.

Error Handling

The server includes comprehensive error handling and will return detailed error messages for debugging. All responses include web interface URLs where applicable for easy navigation to the Moodle web interface.

Web Interface Integration

All returned data includes direct web interface URLs for:

• Course pages
• User profiles
• Assignment pages
• Forum pages

This allows seamless integration between API access and web interface navigation.

Development

Project Structure

mcp/moodle-mcp-server/
├── src/moodle_mcp/
│   ├── __init__.py
│   ├── server.py      # Main server implementation
│   └── main.py        # Entry point
├── pyproject.toml     # Project configuration
└── README.md         # This file

Adding New Tools

To add new Moodle Web Service functions:

1. Add the function to server.py using the @mcp.tool decorator
2. Use make_moodle_api_request() for API calls
3. Add appropriate web interface URLs using the helper functions
4. Update the available operations list in main.py

Testing

The project includes comprehensive tests:

# Run all tests
uv run pytest tests/ -v

# Run simple working tests
uv run python tests/test_simple.py

# Run connectivity tests
uv run python tests/test_connectivity.py

Set up a test environment with:

• A Moodle development instance
• Test user accounts with appropriate permissions
• Sample courses and content for testing

Test files included:

• test_simple.py - Basic functionality tests (always pass)
• test_connectivity.py - Import and connectivity tests
• test_basic.py - Unit tests for individual components
• test_moodle_api.py - Comprehensive API and tool tests

Troubleshooting

Common Issues

1. 403 Forbidden Errors:

   • Run the diagnostic tool: uv run python tests/test_moodle_connection.py
   • Check that web services are enabled in Moodle
   • Verify the token has required permissions
   • Ensure required web service functions are enabled

2. Authentication Errors: Verify your token and ensure it has the required permissions

3. SSL Verification: Set MOODLE_VERIFY_SSL=false for self-signed certificates

4. Missing Functions: Ensure all required web service functions are enabled in Moodle

5. Permission Errors: Verify the token user has appropriate capabilities

Debug Mode

Enable debug logging by setting environment variable:

export MOODLE_DEBUG=true

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues related to:

• MCP Server: Create an issue in this repository
• Moodle Configuration: Consult Moodle documentation
• Web Services: Check Moodle Web Services documentation