All About NTU MCP

An MCP server for NTU Singapore schedules, learning materials, campus navigation, research, faculty, library discovery, news, and campus services.

STARS guide · NTULearn guide · MazeMap guide · DR-NTU guide.

Library guide · Faculty guide · News guide · Campus services guide.

For local stdio usage, install uv and Python 3.10 or newer. Run the public tools from PyPI:

uvx --from all-abt-ntu-mcp==0.1.0-beta.1 all-abt-ntu

The client examples below include the personal extra for authenticated tools.

Chromium

For authenticated STARS, NTULearn and LibFacilities tools, install Chromium once:

uvx --from 'playwright>=1.50,<2' playwright install chromium

Credentials

Public tools need no credentials. For personal tools, opt into native OS keyring storage by running this yourself in a local terminal:

uvx --from all-abt-ntu-mcp==0.1.0-beta.1 all-abt-ntu auth save

Your password is hidden while typing and stored encrypted in your OS keyring, rather than in plaintext files. The server never includes it in MCP responses sent to the LLM.

The prompts save one account for STARS, NTULearn and LibFacilities and enable automatic login/session recovery. Run auth save again to update it, auth status to check storage without revealing credentials, or auth delete to remove it. Replace auth save at the end of the command above with the action you want.

The keyring must be available and unlocked: Secret Service or KWallet on Linux, Keychain on macOS, Credential Manager on Windows. There is no plaintext fallback. Passwords are not accepted through MCP, command arguments, environment variables, .env, or client configuration. Remove any credentials left in your old configuration; the server no longer reads them. More details: shared credential storage.

Some Linux installations do not include a keyring service. Install a provider such as GNOME Keyring or KWallet using your distribution's package manager, then follow your desktop's setup instructions to start and unlock it before running auth save.

Codex

Add to ~/.codex/config.toml:

[mcp_servers.all-abt-ntu-mcp]
command = "uvx"
args = ["--from", "all-abt-ntu-mcp[personal]==0.1.0-beta.1", "all-abt-ntu"]
env_vars = ["DBUS_SESSION_BUS_ADDRESS", "XDG_RUNTIME_DIR"] # for Linux
startup_timeout_sec = 120
tool_timeout_sec = 240

Restart Codex and check codex mcp list. Personal tools use your locally saved keyring account. The env_vars line forwards the Linux desktop session needed for keyring access; start Codex from a terminal where auth status succeeds. These variables contain no NTU credentials.

Claude Code

Register for your user:

claude mcp add --scope user all-abt-ntu-mcp \
  -- uvx --from 'all-abt-ntu-mcp[personal]==0.1.0-beta.1' all-abt-ntu
claude mcp list

Personal tools use your locally saved keyring account. Check claude mcp list or /mcp inside Claude Code. See Claude Code's MCP guide for details.

OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "all-abt-ntu-mcp": {
      "type": "local",
      "command": ["uvx", "--from", "all-abt-ntu-mcp[personal]==0.1.0-beta.1", "all-abt-ntu"],
      "enabled": true,
      "timeout": 240000
    }
  }
}

Personal tools use your locally saved keyring account. Check opencode mcp list. See OpenCode's MCP guide for details.

Manual install

Clone the repository and run the server from a local checkout:

git clone --branch main https://github.com/pitchaya-s/ntu-stars-mcp.git all-abt-ntu-mcp
cd all-abt-ntu-mcp
uv sync
uv run all-abt-ntu

For personal tools, run uv sync --extra personal, then uv run all-abt-ntu auth save in your own terminal. Use uv run all-abt-ntu auth status or auth delete to inspect storage status or remove the account. These commands manage credentials; starting the server still uses uv run all-abt-ntu.

The process uses MCP stdio, so it stays open while its MCP client is connected. Course responses are cached in memory for one hour by default; vacancy snapshots are cached for at most 60 seconds. Set NTU_CACHE_TTL_SECONDS to change the cache time or use 0 to disable caching.

Source layout

src/
├── shared/                 Local/public runtimes, HTTP app, keyring, and parsing
├── stars/
│   ├── mcp_server.py        STARS tool registration and input schemas
│   ├── personal_tools.py    Local authenticated STARS tools
│   ├── room_tools.py        Teaching-based room tool registration
│   ├── room_schemas.py      Typed room constraints and results
│   ├── domain/             Course models, timetable matching and room searches
│   ├── client/             Public NTU requests and caching
│   ├── parser/             Schedule and personal-page parsing
│   └── wish/               WISH login and saved-plan editing
├── ntulearn/
│   ├── mcp_server.py        NTULearn tool registration and input schemas
│   ├── models/             Typed responses grouped by domain
│   ├── client/             Login, sessions, and REST requests
│   ├── parser/             Response and document parsing
│   └── services/           Content, files, mailbox, people, and activity
├── mazemap/
│   ├── mcp_server.py        Public map tool registration and input schemas
│   ├── models.py           Typed place and direction responses
│   ├── client.py           HTTP requests, pacing, and caching
│   └── parser.py           Place and route normalization
├── drntu/
│   ├── mcp_server.py        Public repository tool registration and schemas
│   ├── models.py           Typed publication, facet, and dataset responses
│   ├── client.py           HTTP requests, pacing, and caching
│   ├── parser.py           DSpace metadata and pagination validation
│   ├── repository.py       Publication search, browsing, and file discovery
│   └── datasets.py         Published Dataverse versions and file inventories
├── library/
│   ├── mcp_server.py        Library tool registration and schemas
│   ├── personal_tools.py    Local authenticated facility tool
│   ├── models.py           Catalogue, access and facility responses
│   ├── client.py           OneSearch requests and pagination
│   ├── facilities.py       Public facility directory and map availability
│   ├── session.py          Optional facility login and daily time grids
│   ├── schedule.py         Time-grid validation and normalization
│   └── parser.py           Primo record normalization
├── faculty/
│   ├── mcp_server.py        Public faculty tools and input schemas
│   ├── models.py           Typed profile and research-interest responses
│   ├── client.py           Directory requests, filters, and pagination
│   └── parser.py           Profile cards and interest form parsing
├── news/
│   ├── mcp_server.py        Public news tools and input schemas
│   ├── models.py           Typed story, category, and article responses
│   ├── client.py           News search and bounded article retrieval
│   └── parser.py           Story cards and article body extraction
└── service/
    ├── mcp_server.py        Public campus service tools and input schemas
    ├── models.py           Typed location and filter responses
    ├── client.py           Complete directory collection and local search
    └── parser.py           Contact, hours, and map normalization
tests/
├── stars/                  STARS tests and fictionalized fixtures
├── ntulearn/               NTULearn tests and synthetic fixtures
├── mazemap/                MazeMap tests and synthetic fixtures
├── repository/             DR-NTU tests and synthetic fixtures
├── library/                OneSearch and LibFacilities tests and fixtures
├── faculty/                Faculty directory tests and synthetic fixtures
├── news/                   News search and article tests with synthetic fixtures
├── service/                Campus directory tests and synthetic fixtures
├── hosted/                 Public HTTP protocol, isolation, and deployment checks
├── test_*.py               Keyring, local CLI, and shared lifecycle tests
└── typescript_smoke.mjs     Shared MCP interoperability check

Tools

STARS

Public lookups work without credentials. Planner and Degree Audit use the shared NTU credentials.

Vacancies are available 09:00–22:00 Singapore time; unknown counts are null. Saving a plan replaces its entire course/index list. See the STARS guide for parameters, examples, and sources.

NTULearn

Start with ntulearn_list_courses, then use the returned IDs. See the NTULearn guide for parameters, examples, and sources.

MazeMap

Search for a place first, then use its POI ID for details or directions. See the MazeMap guide for parameters, examples, and sources.

DR-NTU

Public metadata can describe restricted files. See the DR-NTU guide for parameters, examples, and sources.

Library

Use the returned record ID and context for details. See the Library guide for parameters and access limitations.

Faculty

See the Faculty guide for parameters, pagination, and sources.

News

See the News guide for parameters and sources.

Campus services

See the Campus services guide for parameters and directory coverage.

Tests

Personal-data, map, repository, library, faculty, news, and service fixtures are synthetic. Timetable fixtures use fictional course labels and indexes while retaining the HTML structures needed for parser tests. Opt-in live tests print counts and statuses; they do not save academic records or learning materials in the repository.

The offline tests cover keyring storage and failure handling, local credential prompts, session recovery, parsing, scheduling, lossless compaction, output-schema validation, tool calls/errors, and resource discovery. Protocol tests use Python SDK clients and an independent JSON-RPC client over stdio, including protocol versions 2025-06-18 and 2025-11-25:

uv run python -m unittest discover -s tests -t . -v

An optional check uses the official TypeScript SDK. Node dependencies stay in a temporary directory:

NTU_MCP_TEST_SDK="$(mktemp -d)"
npm install --prefix "$NTU_MCP_TEST_SDK" --ignore-scripts --no-audit --no-fund @modelcontextprotocol/sdk@1.32.1
uv run node tests/typescript_smoke.mjs "$NTU_MCP_TEST_SDK"

These interoperability checks use offline fixtures and never edit saved plans.

Hosted HTTP checks cover public-only registration, rejected personal calls, output schemas, both modern and legacy Python SDK clients, Host/Origin validation, request-size limits, and independent serverless event loops. See the HTTP test instructions for the TypeScript client and opt-in live smoke.

Live checks and service-specific testing instructions: STARS · NTULearn · MazeMap · DR-NTU.

Library tests · Faculty tests · News tests · Campus services tests.

Limitation

Access depends on service availability and NTU permissions. Timetables are published schedules; vacancies are snapshots. NTULearn may restrict content, and large collections can return partial results. Inline document reading extracts text without OCR. MazeMap directions are estimates; map data does not establish room availability or current physical access. DR-NTU file metadata does not establish download permission, and the dataset service may interrupt requests with CAPTCHA.

Room searches cover published undergraduate teaching only, not occupancy, graduate classes, exams, other bookings or access permissions. Unplaced lesson venues remain outside room-specific coverage. Library records and access labels do not establish subscription entitlement, anonymous full-text access, or a loanable copy. Facility booking statuses do not establish occupancy. MFA stops library login; no borrowing or facility bookings are submitted.

Disclaimer

This is an independent project and is not affiliated with, sponsored by, or endorsed by Nanyang Technological University (NTU), Singapore.

Your NTU credentials are retrieved locally from your OS keyring and submitted over HTTPS to NTU or its Microsoft sign-in service. They are never returned through MCP. Academic data returned by tools is visible to the AI client. Keyring storage protects credentials at rest; it does not isolate them from other programs or agents allowed to access your unlocked keyring or the server process.