mcpUPB

"What's due this week?" · "Summarize the latest announcement" · "Build a study plan from this course" · "Sync all my Algorithms material to markdown"

It talks to Moodle's official Web Services REST API (no browser scraping), so it's fast and robust. Although it's tuned for UPB Virtual, it works against any Moodle site with web services enabled — just change MOODLE_BASE_URL.

⚠️ Personal tool. It acts on your account with your token. Respect your institution's terms of service and only access data you're entitled to.

How it works

flowchart LR
    A["🤖 AI Assistant<br/>(Claude, mcpjam…)"] -- MCP / stdio --> B
    subgraph B ["mcp-upb server"]
        T["🛠️ Tools"]
        R["📚 Resources<br/>upb://…"]
        P["💬 Prompts"]
    end
    B --> C["Moodle REST client<br/>(token auth)"]
    C -- "webservice/rest/server.php" --> M[("🎓 UPB Virtual<br/>Moodle")]
    B --> V["🔄 Vault sync"]
    V --> D["🗂️ vault/<br/>markdown + files"]

A typical request flows straight through to the LMS and back as clean JSON:

sequenceDiagram
    participant U as You
    participant AI as AI Assistant
    participant S as mcp-upb
    participant M as Moodle
    U->>AI: "What's due this week?"
    AI->>S: weekly_digest()
    S->>M: core_calendar / forum / messages
    M-->>S: JSON
    S-->>AI: deadlines + announcements + alerts
    AI-->>U: "3 things due, 1 overdue…"

Related MCP server: Moodle MCP Server

Features

Tools

Resources

Browsable upb:// URIs a client can attach as context:

• upb://courses — enrolled courses

• upb://course/{id} — a course's contents

• upb://course/{id}/assignments — a course's assignments

Prompts

Ready-made commands: weekly_summary, study_plan (arg: course), assignment_checklist (arg: assignment).

Setup

npm install
cp .env.example .env        # Windows: copy .env.example .env
npm run get-token           # enter your UPB username + password

get-token calls login/token.php and prints a MOODLE_TOKEN=... line. Paste it into .env. Your password is never stored — only the token, which lives in .env (gitignored).

If get-token fails with an invalid-login error, your account may use SSO/Google login, which can disable password-based tokens. In that case generate a token manually in Moodle under Preferences → Security keys and paste it into .env.

Environment variables

Testing with mcpjam

mcpjam spawns the server as a stdio process and gives you a UI to run tools, browse resources and chat against an LLM.

1. Launch the inspector (opens http://127.0.0.1:6274):

   npm run inspect          # = npx @mcpjam/inspector@latest

2. Add Server → STDIO:

   Field	Value
   Transport	STDIO
   Command	npx
   Arguments	tsx src/server.ts
   Working directory	the project root
   Environment	MOODLE_TOKEN=<token> (most reliable; avoids .env/cwd issues)

   For the compiled build: npm run build, then Command node, Arguments dist/server.js.

3. Open Tools and start with whoami. Then list_courses → copy an id → get_course, list_assignments, get_grades, etc.

Use with Claude / other MCP clients

After npm run build, add to your client's MCP config:

{
  "mcpServers": {
    "upb": {
      "command": "node",
      "args": ["C:/Users/User/Desktop/GitHub/mcpUPB/dist/server.js"],
      "env": { "MOODLE_TOKEN": "your-token-here" }
    }
  }
}

Scripts

Notes & limitations

• pdf_to_markdown / sync_course extract the PDF text layer only (good for slides and notes; no tables/math reconstruction). For high-fidelity conversion, plug in a Docling / PyMuPDF4LLM helper — the rest of the pipeline is unchanged.

• Available data depends on what your Moodle role/capabilities expose via web services; some tools may return errors if a function is disabled site-wide.

Project structure

src/
  server.ts          MCP server entry (stdio)
  config.ts          env config
  tools.ts           tool registrations
  resources.ts       upb:// resources
  prompts.ts         prompt templates
  moodle/
    client.ts        REST transport (token, params, file urls)
    api.ts           typed Moodle function wrappers
  storage/
    cache.ts         incremental-sync cache
  vault/
    sync.ts          sync_course / sync_all
    pdf.ts           pdf -> markdown
    markdown.ts      vault writer
scripts/
  get-token.ts       credentials -> token helper

License

MIT