neptun-api

The most complete Python API wrapper for the Hungarian Neptun university system. Reverse-engineered from the Angular web client, covering 1,100+ endpoints across 75+ controllers.

Built and tested against Obuda University, but should work with any Neptun instance by changing the base URL. Instances that require two-factor login (e.g. University of Debrecen) are supported, see Two-factor authentication.

Installation

pip install -e .                   # core API wrapper
pip install -e ".[survey]"         # + automated survey filler
pip install -e ".[all]"            # + survey + dev/test tools

For survey auto-fill, also run after install:

python -m playwright install chromium

Requirements: Python 3.11+, requests

Quick Start

from neptun_api import NeptunAPI

api = NeptunAPI("YOUR_NEPTUN_CODE", "YOUR_PASSWORD",
                base_url="https://neptun.uni-obuda.hu/ujhallgato/api/")
api.authenticate()

# Get your GPA
averages = api.get_term_averages()
for term in averages["termAveragesByTrainings"]:
    print(f'{term["average"]} avg, {term["creditIndex"]} credit index')

# Get the grade for every subject across all terms (full transcript).
# This is the reliable way to read grades — including midterm marks and
# transfer/recognised grades — which get_subject_results_list does not return
# on many instances. (get_subject_result / get_subject_results_list are kept
# only as raw endpoint wrappers; prefer these.)
for g in api.get_all_grades():
    print(f'{g["term"]} [{g["subjectCode"]}] {g["subjectName"]}: {g["grade"]} ({g["gradeName"]})')

# Or one subject's result by its subject id
result = api.get_subject_grade(subject_id)   # {"resultValue": 4, "resultName": "Jó", "passed": True}

# Get current courses
terms = api.get_taken_subjects_terms()
subjects = api.get_taken_subjects(terms[1]["value"])  # [1] skips "0. felev"
for s in subjects:
    print(f'[{s["subjectCode"]}] {s["subjectName"]} - {s["subjectCredit"]} credits')

# Get unread messages
count = api.get_unread_message_count()
messages = api.get_received_messages(0, 20)

# Calendar
from datetime import datetime
events = api.get_calendar_events(datetime(2025, 9, 1), datetime(2026, 1, 31))

# Finances
impositions = api.get_financial_impositions()

# Auto-fill all pending semester surveys (rating 1-5)
from neptun_api import fill_all_surveys
results = fill_all_surveys(api, rating=5)

What's Covered

Total: 1,100+ methods

Auto-Fill Semester Surveys

Neptun's end-of-semester opinion surveys (Unipoll) can be filled automatically using browser automation. The filler handles both English and Hungarian survey interfaces.

from neptun_api import NeptunAPI, fill_all_surveys

api = NeptunAPI("code", "password", base_url="https://neptun.uni-obuda.hu/ujhallgato/api/")
api.authenticate()

# Fill all pending surveys with 5/5 rating
results = fill_all_surveys(api, rating=5)

# Custom rating (1-5) and optional text comment
results = fill_all_surveys(api, rating=4, text_answer="Great course!")

# Dry run — fills forms but doesn't submit
results = fill_all_surveys(api, rating=5, dry_run=True)

# Show browser window (useful for debugging)
results = fill_all_surveys(api, rating=5, headless=False)

Each result dict contains subject, course, and status ("submitted", "failed", or "error").

Requires: pip install playwright && python -m playwright install chromium

MCP Server

Run Neptun as an MCP server so any MCP-compatible AI (Claude Desktop, Claude Code, Cursor, etc.) can access your university data.

Stdio (local — Claude Desktop / Claude Code):

pip install -e ".[mcp]"
python -m neptun_api --username YOUR_CODE --password YOUR_PASS

SSE (remote / port-forwarded):

python -m neptun_api --username YOUR_CODE --password YOUR_PASS --transport sse --port 8000

Streamable HTTP:

python -m neptun_api --username YOUR_CODE --password YOUR_PASS --transport streamable-http --port 8000

Or use environment variables:

export NEPTUN_USERNAME=YOUR_CODE
export NEPTUN_PASSWORD=YOUR_PASS
export NEPTUN_BASE_URL=https://neptun.uni-obuda.hu/ujhallgato/api/
export NEPTUN_TOTP_SECRET=BASE32SECRET   # only for two-factor instances (see below)
python -m neptun_api --transport sse --port 8000

Claude Desktop config

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "neptun": {
      "command": "python",
      "args": ["-m", "neptun_api"],
      "env": {
        "NEPTUN_USERNAME": "YOUR_CODE",
        "NEPTUN_PASSWORD": "YOUR_PASS"
      }
    }
  }
}

There is also an installed console command equivalent to python -m neptun_api:

neptun-mcp --username YOUR_CODE --password YOUR_PASS

Available MCP Tools (23)

Authentication

The wrapper uses JWT Bearer tokens. Authentication is automatic — if your token expires mid-session, the client re-authenticates and retries transparently.

api = NeptunAPI("code", "password", base_url="https://your-university.hu/ujhallgato/api/")
api.authenticate()

# Token refresh
api.refresh_token()

# Auto-retry on 401 is built in — you don't need to handle token expiry

Two-factor authentication

Some universities (for example the University of Debrecen) require an authenticator-app code on every login. Their Neptun answers the first login with HTTP 202 and "isTwoFactorRequired": true instead of a token; the official web client then re-sends the login with the 6-digit code in a token field. authenticate() does the same, and you have three ways to supply the code:

from neptun_api import NeptunAPI, NeptunTwoFactorRequired

DEBRECEN = "https://www-h-ng.neptun.unideb.hu/hallgato_ng/api/"

# 1. Pass the code from your authenticator app for this login only
api = NeptunAPI("code", "password", base_url=DEBRECEN)
api.authenticate(totp_code=input("Authenticator code: "))

# 2. Ask for it whenever the client needs to (re-)authenticate
api = NeptunAPI("code", "password", base_url=DEBRECEN,
                two_factor_callback=lambda: input("Authenticator code: "))
api.authenticate()

# 3. Fully unattended: give the TOTP secret and codes are generated for you
#    (this is the base32 key behind the QR code shown when you registered the
#    authenticator — most apps let you view or export it; otherwise delete the
#    key in Neptun and register it again, noting the key this time).
api = NeptunAPI("code", "password", base_url=DEBRECEN, totp_secret="JBSWY3DPEHPK3PXP")
api.authenticate()

If none of these is provided and the instance asks for a second factor, authenticate() raises NeptunTwoFactorRequired (a NeptunAuthError). A wrong or expired code raises NeptunAuthError; after repeated failed logins Neptun may also demand a captcha, which surfaces as NeptunCaptchaRequired — log in once through the website to clear it.

Option 1 only covers the initial login: if the session later expires (401) the client cannot re-authenticate without a fresh code, so long-running scripts should use option 2 or 3. generate_totp(secret) is exported if you need the current code yourself; it is a dependency-free RFC 6238 implementation (6 digits, 30 s, SHA-1, the Google Authenticator defaults Neptun uses).

Raw Requests

For endpoints not yet wrapped, use the raw methods:

# GET
data = api.raw_get("SomeController/SomeAction", params={"key": "value"})

# POST
data = api.raw_post("SomeController/SomeAction", data={"key": "value"})

# PUT / DELETE
data = api.raw_put("SomeController/SomeAction", data={"key": "value"})
data = api.raw_delete("SomeController/SomeAction", params={"key": "value"})

Other Universities

Change the base_url to point to your university's Neptun instance:

# Obuda University
api = NeptunAPI("code", "pass", base_url="https://neptun.uni-obuda.hu/ujhallgato/api/")

# BME
api = NeptunAPI("code", "pass", base_url="https://neptun.bme.hu/ujhallgato/api/")

# ELTE
api = NeptunAPI("code", "pass", base_url="https://neptun.elte.hu/ujhallgato/api/")

# University of Debrecen (two-factor login, see Authentication above)
api = NeptunAPI("code", "pass", base_url="https://www-h-ng.neptun.unideb.hu/hallgato_ng/api/",
                two_factor_callback=lambda: input("Authenticator code: "))

# Any Neptun instance — take the URL of the new student web (it ends in
# /ujhallgato/ or /hallgato_ng/ depending on the university) and append api/

Note: Not all universities may have the same endpoints enabled. Some features (booking, theses, practice) may return 403 depending on your institution's configuration.

Running Tests

# Unit tests
pip install -e ".[dev]"
pytest

# Live integration test (requires NEPTUN_USERNAME / NEPTUN_PASSWORD env vars)
NEPTUN_USERNAME=YOUR_CODE NEPTUN_PASSWORD=YOUR_PASS python tests/test_live_comprehensive.py

Project Structure

neptun_api/
  __init__.py        # Public exports
  __main__.py        # Entry point for python -m neptun_api
  client.py          # API wrapper (1,100+ methods)
  mcp_server.py      # MCP server (stdio / SSE / streamable-http)
  survey_filler.py   # Automated Unipoll survey filler (Playwright)
  models.py          # Dataclasses for common response types
  exceptions.py      # NeptunAuthError, NeptunRequestError
tests/
  test_client.py             # client unit tests (incl. grade API)
  test_models.py             # dataclass model tests
  test_mcp_server.py         # guards MCP tools against client drift
  test_live_comprehensive.py # live smoke test (run directly, needs creds)
docs/
  request_forms.md           # guide to the request-form (petition) endpoints

License

MIT