Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

All About NTU

Explore NTU services from your terminal or connect them to an AI assistant. Search courses and library resources, navigate campus, check shuttle arrivals, and access your own learning materials and student services through a single application.

Documentation · CLI guide · MCP setup · Service reference · Report an issue

All About NTU provides two interfaces to the same services:

  • CLI: run ntu commands directly in your terminal, with readable output or JSON for scripts.
  • MCP: give a compatible AI client access to selected NTU tools through a local server or the hosted public server.

Quickstart

Install uv and Python 3.10 or newer. Then choose how you want to use All About NTU:

Use the CLI

uv tool install 'all-abt-ntu[cli,personal]@latest'
ntu cli setup
ntu --help

Connect an MCP client

uvx --from 'all-abt-ntu[cli,mcp,personal]@latest' ntu mcp setup

Setup lets you choose a profile, enable tools, and configure Codex, Claude Code, or OpenCode. You can also connect to the hosted public server without installing anything locally.

For personal services such as NTULearn and One Stop, use CLI setup to save your credentials and install Chromium. You can skip these steps if you only use public services; no NTU account is needed for those.

Your password stays in your OS keyring. It is entered through a hidden prompt, stored locally with no plaintext fallback, and sent only to NTU or its Microsoft sign-in service when needed. It is never returned through MCP or shared with your AI client.

Available services

Service What you can do CLI Reference
STARS Search courses, explore prerequisites and indexes, view schedules and manage plans ntu stars STARS
NTULearn Browse enrolled courses, learning materials, announcements, grades and calendars ntu learn NTULearn
CareerAxis Find opportunities, employers, career events and resources ntu career CareerAxis
MazeMap Search campus places and get walking directions ntu map MazeMap
DR-NTU Discover research publications, repository collections and datasets ntu research DR-NTU
Library Search the catalogue, inspect records and explore facilities ntu library Library
Faculty Find faculty members and research interests ntu faculty Faculty
News Browse and search NTU news ntu news News
Campus Services Find food, shops, clinics and other campus services ntu services Campus Services
Omnibus Check shuttle routes, stops, arrivals and service status ntu bus Omnibus
One Stop @ SAC Explore the catalog and manage requests, appointments and other student services ntu onestop One Stop

The service references include CLI commands, MCP tools, arguments, outputs and service-specific limits.

Authentication

If you saved your credentials during setup, you do not need to save them again. To save or manage them later, run:

ntu auth save
ntu auth status
ntu auth delete

Your password is entered through a hidden prompt and stored locally in your OS keyring; there is no plaintext fallback. Your keyring must be available and unlocked. Never enter a password into an AI conversation or MCP client configuration.

If you use MCP through uvx without installing the CLI, save credentials with:

uvx --from 'all-abt-ntu[cli,personal]@latest' ntu auth save

See credentials and platform setup for more details.

CLI

Installation

For public and authenticated services:

uv tool install 'all-abt-ntu[cli,personal]@latest'

For public services only, install the smaller CLI extra:

uv tool install 'all-abt-ntu[cli]@latest'

See the CLI installation guide for browser-cookie support.

Manual CLI installation

To run the CLI from a local checkout:

git clone https://github.com/pitchaya-s/all-abt-ntu.git
cd all-abt-ntu
uv sync --no-default-groups --extra cli --extra personal
uv run --no-sync playwright install chromium
uv run --no-sync ntu --help

For public services only, omit --extra personal and the Chromium installation. Use uv run --no-sync ntu auth save to save credentials for personal services. See the manual CLI guide for environment activation and platform-specific details.

Examples

Search courses, inspect a course and explore its indexes and prerequisites:

ntu stars courses search "data structures" --year 2026 --semester 1 --limit 10 --offset 0
ntu stars course ZZ0001 --year 2026 --semester 1
ntu stars indexes ZZ0001 --year 2026 --semester 1 --limit 10 --offset 0
ntu stars prerequisites ZZ0001 --year 2026 --semester 1 --prerequisite-depth 2 --dependent-depth 2

Browse NTULearn content and download a file or video:

ntu learn courses --limit 20 --offset 0
ntu learn content ZZ0001 --limit 20 --offset 0
ntu learn attachments ZZ0001 "_67890_1" --limit 20 --offset 0
ntu learn files download ZZ0001 "_67890_1" "_24680_1" --output "./lecture.pdf" --max-bytes 20000000
ntu learn videos download ZZ0001 "_67890_1" --output "./lecture.mp4" --max-mb 500

ZZ0001 and the IDs above are fictional. Replace them with your course and content IDs from the preceding commands. Supported NTULearn content URLs can also be used in place of course and content IDs; see the NTULearn CLI guide. Downloads require confirmation.

Explore the rest of campus:

ntu map search "LT1" --limit 10 --offset 0
ntu bus arrivals --route Blue --stop "North Spine" --source shuttle
ntu library search "machine learning" --field title --match contains --limit 10 --offset 0
ntu news search "artificial intelligence" --sort latest --page 1
ntu services search "coffee" --location "North Spine" --limit 10 --offset 0

Run ntu --help, ntu stars --help, or add --help to a command to see its available arguments. Many data commands support --json, pagination options and --refresh where applicable:

ntu map search "LT1" --limit 10 --offset 0 --json

See the CLI guide and complete command reference for more examples and options.

MCP

MCP connects NTU tools to compatible AI clients. The local server offers a public profile and a personal profile; personal tools use your locally saved credentials. You choose which tools are available, and actions and downloads require confirmation.

Local setup

uvx --from 'all-abt-ntu[cli,mcp,personal]@latest' ntu mcp setup

To review or change tools later:

uvx --from 'all-abt-ntu[cli,mcp,personal]@latest' ntu mcp tools list
uvx --from 'all-abt-ntu[cli,mcp,personal]@latest' ntu mcp tools list --all
uvx --from 'all-abt-ntu[cli,mcp,personal]@latest' ntu mcp tools disable news
uvx --from 'all-abt-ntu[cli,mcp,personal]@latest' ntu mcp tools enable stars

To run a public stdio server directly:

uvx --from 'all-abt-ntu[mcp]@latest' ntu mcp --profile public

The MCP setup guide covers client configuration, profiles, Chromium and manual installation. See the tool reference for available tools.

Manual MCP installation

For interactive setup and personal tools from a local checkout:

git clone https://github.com/pitchaya-s/all-abt-ntu.git
cd all-abt-ntu
uv sync --no-default-groups --extra cli --extra mcp --extra personal
uv run --no-sync ntu mcp setup

For a public server, install only the MCP extra and start the server directly:

uv sync --no-default-groups --extra mcp
uv run --no-sync ntu mcp --profile public

If you didn't save credentials during setup, use uv run --no-sync ntu auth save. The manual MCP guide has more details.

Hosted public server

Add the following URL to a client that supports remote MCP servers, using Streamable HTTP and no authentication:

https://all-abt-ntu-mcp.vercel.app/mcp

The hosted server provides public, read-only information. Personal services require the local server. See the hosted MCP guide for details.

Documentation and contributing

Browse the documentation site for getting started, service guides, architecture and security, known issues, and limitations.

To work on the project, see the development guide, testing guide, and contributing guide. Preview the documentation locally with:

uvx --from mkdocs-material mkdocs serve

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.

Use this software only to access accounts and materials you are authorized to access. Do not download, copy, store, or redistribute course recordings, lecture files, library resources, research data, or other restricted or copyrighted material unless you have permission. Follow NTU policies, copyright and license notices, source-service terms, and applicable law. Do not bypass authentication, CAPTCHA, DRM, paywalls, or other access restrictions. You are responsible for ensuring your access, downloads, retention, and reuse are authorized.

Metadata

Release files for all-abt-ntu 0.1.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for all-abt-ntu 0.1.0b1
File Size Uploaded Provenance Actions
all_abt_ntu-0.1.0b1.tar.gz 646.2 kB With provenance Details for all_abt_ntu-0.1.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for all-abt-ntu 0.1.0b1
File Interpreter ABI Platform Actions
all_abt_ntu-0.1.0b1-py3-none-any.whl Python 3 none any Details for all_abt_ntu-0.1.0b1-py3-none-any.whl

Total release size: 976.3 kB

Release files / all_abt_ntu-0.1.0b1.tar.gz

Download URL all_abt_ntu-0.1.0b1.tar.gz
Size 646.2 kB
Tags Source
SHA-256 checksum
How to use checksums
74e846d1e3a7271bc4ca4d7feae88110049ef299e6d6f59a9b5bfc18294c1285
BLAKE2b-256 checksum
How to use checksums
9a719ddafb0d2efd3a13a7ff0c282b63d8cd4c8dcda209831649b08d85dd8a04
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / all_abt_ntu-0.1.0b1-py3-none-any.whl

Download URL all_abt_ntu-0.1.0b1-py3-none-any.whl
Size 330.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ae5b3631e9547782296575c4de12b0367191a29675ae4733ef7ae197a37192fa
BLAKE2b-256 checksum
How to use checksums
a6e51d07f1b956f19e3198649e681519a7f2745cb49e89570e2eea982e900167
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for all-abt-ntu 0.1.0b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for all_abt_ntu-0.1.0b1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page