moses-mcp

An MCP server for discovering degree programs and modules in Moses — TU Berlin's course, exam, and module planning system. It talks to Moses' official REST API (https://moseskonto.tu-berlin.de/moses/api/v2), which innoCampus (who run Moses) can provision on request.

Scope

• Search and browse degree programs (Studiengänge) and their curriculum structure (Pflichtbereich, Wahlpflichtbereich, ...).

• Search modules and read full module descriptions, including exam type (Prüfungsform) and which other degree programs use a given module.

• Out of scope: Vorlesungsverzeichnis (VVZ)/timetables, and anything requiring login (exam registration, editing module data).

Related MCP server: OpenAlex MCP Server

Tools

Example things you can ask an MCP client connected to this server:

• "Which modules are mandatory (Pflichtmodul) for the Informatik B.Sc.?"

• "Of those, which use a Portfolioprüfung instead of a written exam?"

• "Recommend some Computer Vision modules for the Computer Science Master's."

• "What other degree programs can take module 40022?"

• "Make me a 6-semester study plan for the Informatik B.Sc. specializing in Theoretical Computer Science" (respects each area's StuPO passing rules, not just credit totals)

Requirements

• Node.js 20 or later

• A Moses API token (see below)

API access

There's no self-service signup — email innoCampus (who run Moses) and ask for API access; they'll issue a token and tell you which endpoints are enabled for it. Keep the token secret: it authenticates as you, and the endpoint owners can rate-limit or block API keys that generate excessive load (e.g. bulk-scanning without cause), so use refresh: true sparingly and avoid scripting bulk queries beyond what this tool already does.

Setup

git clone <this-repo>
cd moses-mcp
npm install
cp .env.example .env   # then edit .env and set API_TOKEN=<your token>
npm run build

This produces a runnable server at dist/index.js, which communicates over stdio (standard MCP transport). The server reads .env itself on startup (resolved next to its own install location, not the caller's working directory), so a .env file in this project directory is enough — you don't need to configure the token separately in your MCP client, though you can (see below) if you'd rather not keep it in a file.

Using it with an MCP client

Claude Code

claude mcp add moses -- node /absolute/path/to/moses-mcp/dist/index.js

This registers the server at local scope (just this project, just you). Use -s user to make it available in every project, or -s project to check a shared .mcp.json into this repo for teammates. Check claude mcp list or run /mcp inside a session to confirm it's connected.

Claude Desktop / other stdio clients

Add it to your client's MCP server config, pointing at the built dist/index.js. For example, in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "moses": {
      "command": "node",
      "args": ["/absolute/path/to/moses-mcp/dist/index.js"]
    }
  }
}

Any MCP client that supports stdio servers can use this the same way — point it at node dist/index.js. If you'd rather not keep the token in .env, most clients also let you set per-server environment variables directly in their config (e.g. add "env": {"API_TOKEN": "..."} alongside "command"/"args" above) instead.

Enabling cross-program module usage lookups

get_module_details's usedInPrograms (which other degree programs use a module) needs a reverse-lookup index that Moses' API doesn't support querying directly — building it means scanning the full assignment tables (~445k records), which takes on the order of 10-15 minutes. So it's never built automatically; run it explicitly, and re-run occasionally to refresh (it's cached for 7 days regardless):

npm run build-usage-index

Until this has been run at least once, usedInPrograms comes back as an empty list rather than blocking tool calls.

Development

npm install
npm run dev     # run the MCP server via stdio (tsx, no build step)
npm run build   # compile to dist/
npm test        # run unit tests against fixture data (no network)
npm run e2e     # build, then exercise all 5 tools against the LIVE API

src/api/client.ts is the typed REST client (token auth via X-API-Key, batched idlist lookups, a small concurrency cap). src/api/entities.ts has the API's entity shapes. The trickiest part of src/services/degreePrograms.ts is that Moses' curriculum data comes in two structurally different shapes depending on the StuPO: a newer studiengangsbereich model, and an older per-semester bolognamodulliste model still used by some programs (Informatik B.Sc. among them) — get_degree_program_structure/list_area_modules detect and handle both. src/services/moduleUsageIndex.ts builds the cross-program usage index described above. scripts/e2e-check.ts runs the built server end-to-end against the live API.

Troubleshooting

• A degree program's curriculum looks empty / mapped: false: not every Studien-/Prüfungsordnung (StuPO) has curriculum data mapped yet. get_degree_program_structure automatically tries a few recent StuPOs to find one with data if you don't specify stupo/semester explicitly.

• Stale results after a Moses update: pass refresh: true to any tool to bypass the cache, or delete the .cache/ directory.

• get_module_details's usedInPrograms is always empty: run npm run build-usage-index at least once — see above.

• A tool errors unexpectedly: the Moses API is under active development and has some known rough edges (e.g. idlist silently doesn't filter on a couple of endpoints — already worked around in src/api/client.ts). If a new one shows up, issues/PRs welcome.