# Moodle MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server + REST API that connects **Claude, ChatGPT, Google Gemini, and any AI model** to any Moodle LMS instance. Built in Go.

Students can interact with their Moodle account through their favorite AI — view courses, check grades, track deadlines, submit assignments, and read notifications.

**Works with:**
- ✅ **Claude** (Desktop, Code) - via MCP (easiest!)
- ✅ **ChatGPT** (Plus) - via REST API + Actions
- ✅ **Google Gemini** - via REST API + Apps Script
- ✅ **Any AI** - via REST API (HTTP endpoints)

## Features

| Tool | Description |
|------|-------------|
| `login` | Authenticate with your Moodle site interactively |
| `get_site_info` | View Moodle site and user info |
| `get_user_profile` | View your profile details |
| `list_courses` | List all enrolled courses |
| `get_course_contents` | View sections, resources, and activities |
| `get_course_details` | View course metadata |
| `get_grades` | View grades for a specific course |
| `get_grades_overview` | View grade summary across all courses |
| `get_assignments` | View assignments for a course |
| `get_upcoming_assignments` | View upcoming assignments across all courses |
| `submit_assignment` | Submit text content for an assignment |
| `get_calendar_events` | View upcoming calendar events |
| `get_upcoming_deadlines` | View consolidated deadlines sorted by urgency |
| `get_notifications` | View messages and notifications |

## Requirements

- Claude Desktop (macOS, Windows, or Linux)
- A Moodle account at any institution

## Quick Start

**Choose your AI platform:**

| Your AI | Guide | Time |
|---------|-------|------|
| 🤖 **Claude** (Recommended) | [Windows](WINDOWS_SETUP.md) / [macOS](MAC_SETUP.md) | 2 min |
| 💬 **ChatGPT** | [ChatGPT Setup](CHATGPT_SETUP.md) | 15 min |
| 🔍 **Google Gemini** | [Gemini Setup](GEMINI_SETUP.md) / [Gemini Windows](GEMINI_WINDOWS_SETUP.md) | 20 min |
| 🌐 **Multiple AIs** | [All Models Guide](ALL_MODELS_SETUP.md) | 1 hour |

**Start here:** If you use Claude, follow the Windows/macOS guide above (2 minutes!)

**Not a coder?** All guides have step-by-step instructions with no technical knowledge needed.

---

## Installation (Easiest)

### For Windows (PowerShell)

Open PowerShell and run:

```powershell
irm https://raw.githubusercontent.com/Jawadh-Salih/moodle-mcp-server/main/install.ps1 | iex
```

This will automatically download and install the binary to `C:\Users\YourName\moodle-mcp\moodle-mcp.exe`

### For macOS / Linux (Bash)

Open Terminal and run:

```bash
curl -fsSL https://raw.githubusercontent.com/Jawadh-Salih/moodle-mcp-server/main/install.sh | bash
```

This will automatically download and install the binary to `~/.moodle-mcp/moodle-mcp`

### Manual Installation (For Developers)

If you want to build from source:

```bash
# Clone the repository
git clone https://github.com/Jawadh-Salih/moodle-mcp-server.git
cd moodle-mcp-server

# Build the binary
go mod tidy
go build -o moodle-mcp ./cmd/moodle-mcp/
```

## Usage

### Option 1: Interactive Login (Recommended)

Just start the server with no configuration. When you chat with Claude, use the `login` tool to authenticate:

> "Log in to my Moodle at https://online.uom.lk with username student@uom.lk"

Claude will ask for your password and authenticate you.

### Option 2: Environment Variables

Set credentials as environment variables for automatic login:

```bash
export MOODLE_URL=https://online.uom.lk
export MOODLE_USERNAME=your-username
export MOODLE_PASSWORD=your-password
```

Or if you have a Moodle API token:

```bash
export MOODLE_URL=https://online.uom.lk
export MOODLE_TOKEN=your-api-token
```

## Claude Desktop Configuration

### If you used the auto-installer:

The installer will show you the exact path. Just copy it!

### Manual Configuration

Find your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`

#### Option A: Interactive login (Recommended - no credentials in config)

```json
{
  "mcpServers": {
    "moodle": {
      "command": "/path/to/moodle-mcp"
    }
  }
}
```

Then in Claude, use the `login` tool to authenticate interactively.

#### Option B: With credentials stored

```json
{
  "mcpServers": {
    "moodle": {
      "command": "/path/to/moodle-mcp",
      "env": {
        "MOODLE_URL": "https://online.uom.lk",
        "MOODLE_USERNAME": "your-username",
        "MOODLE_PASSWORD": "your-password"
      }
    }
  }
}
```

**Windows example paths:**
- Auto-installer: `C:\Users\YourName\moodle-mcp\moodle-mcp.exe`
- Manual build: `C:\Users\YourName\Go\bin\moodle-mcp.exe`

**macOS example paths:**
- Auto-installer: `/Users/yourname/.moodle-mcp/moodle-mcp`
- Manual build: `/Users/yourname/moodle-mcp-server/moodle-mcp`

## Supports Multiple AI Platforms

### Via MCP (Claude Only)
- ✅ Claude Desktop (macOS, Windows, Linux)
- ✅ Claude Code (VSCode, terminal)

### Via REST API (ChatGPT, Gemini, Any AI)
- ✅ ChatGPT (with Custom GPT Actions)
- ✅ Google Gemini (with Apps Script)
- ✅ Any AI with HTTP client access
- ✅ Custom scripts and integrations

See [All Models Setup](ALL_MODELS_SETUP.md) for detailed instructions for each platform.

## Running the REST API Server

For ChatGPT, Gemini, or other AI models, run the REST API mode:

```bash
# Start REST API server
go run ./cmd/moodle-mcp/ -mode rest -port 8080

# Or if you built the binary:
./moodle-mcp -mode rest -port 8080

# View API docs
curl http://localhost:8080/api/docs
```

The server listens on `http://localhost:8080` and exposes REST endpoints:
- `POST /api/login` - Authenticate
- `GET /api/courses` - List courses
- `GET /api/grades?course_id=123` - Get grades
- `GET /api/assignments/upcoming` - Upcoming assignments
- And more!

For production (ChatGPT/Gemini), deploy to cloud:
- [Google Cloud Run](DEPLOYMENT_GUIDE.md) (Recommended for Gemini)
- [Heroku](DEPLOYMENT_GUIDE.md) (Simplest)
- [DigitalOcean](DEPLOYMENT_GUIDE.md) (Most control)

---

## Example Conversations

Once connected, you can ask Claude things like:

- "Show me my enrolled courses"
- "What are my grades in CS101?"
- "What assignments are due this week?"
- "Show me the contents of my Data Structures course"
- "Do I have any unread notifications?"
- "What deadlines are coming up in the next 7 days?"

## How It Works

This server uses Moodle's [Web Services REST API](https://docs.moodle.org/dev/Web_service_API_functions) with the `moodle_mobile_app` service token. This service is enabled by default on most Moodle installations, so no admin setup is needed.

## Troubleshooting

**"Invalid login" error:** Double-check your username and password. Some institutions use email as username, others use a separate ID.

**"Web service not available" error:** Your Moodle admin may have disabled the mobile web service. Ask them to enable it under *Site administration > Plugins > Web services > Mobile*.

**Grades not showing:** The grade report API requires the `gradereport/user:view` capability, which is standard for students but may be restricted on some sites.

## License

MIT