SkillAgentSearch skills...

neptun-api

The most complete Python wrapper for the Hungarian Neptun university system API

Install / Use

claude mcp add IdrissaMaiga -- npx -y github:IdrissaMaiga/neptun-api

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

80/100

Category

Automation

Supported Platforms

Claude Code
Claude Desktop

Our assessment of neptun-api

neptun-api scores 80/100 on our quality scale, 2452nd of 2,790 Automation skills we index.

Its MCP Server is 13 KB long, well organised into 50 sections with 16 code examples: a thorough specification that gives an agent plenty to work with.

It has 3 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
30/30
Structure
20/20
Description
12/15
Adoption
3/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 20 days ago, so neptun-api is actively maintained.
  • Our last check on 2026-09-23 found the source still online.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 87/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-06. Automated pattern scan on 2026-10-06. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.

neptun-api compared with similar skills

All 4 of these similar skills score higher than neptun-api; compare them before choosing.

SkillScoreStarsUpdatedFormat
neptun-api (this skill)by IdrissaMaiga80320d agoMCP Server
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
rufloby ruvnet10081.9ktodayCLAUDE.md
headroomby headroomlabs-ai10079.8ktodayCLAUDE.md
CowAgentby zhayujie10048.0ktodayCLAUDE.md

Frequently asked questions

How do I install neptun-api?
Run claude mcp add IdrissaMaiga -- npx -y github:IdrissaMaiga/neptun-api. The install tabs above show the steps for each supported agent.
Which AI agents does neptun-api work with?
It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
Is neptun-api safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is MIT-licensed and scores 87/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is neptun-api still maintained?
The repository was last updated 20 days ago, so neptun-api is actively maintained.

neptun-api

Python License Endpoints

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

| Area | Methods | Examples | |---|---|---| | Dashboard | 6 | GPA, credit progress, exam entries | | Messages | 18+ | Inbox, sent, deleted, compose, recipients | | Calendar | 29 | Events, export, subscriptions, filters | | Subjects & Courses | 60+ | Taken subjects, registration, course changes | | Exams | 30+ | Registration, results, remaining exams | | Grades & Advancement | 21 | Term averages, credit index, curriculum progress | | Financial | 50+ | Impositions, payments, invoices, scholarships | | Personal Data | 113 | Addresses, emails, phones, documents, language exams | | Documents | 49 | Upload, download, containers, folders | | Timetable & Rooms | 38+ | Room schedule, booking, institutional timetable | | Curriculum | 12 | Templates, subject groups, completable subjects | | Request Forms | 62 | Submit, track, attachments, judgements | | Student Card | 12 | Claims, address, status | | Tasks | 28 | Assignments, documentation, deadlines | | Questionnaires | 17 + auto-fill | List, fill out via browser automation, view results | | Consultation | 12 | Appointments, sign up, drop | | E-Materials | 28 | Course materials, downloads | | Online Occasions | 24 | Virtual classes, Webex/Teams links | | Thesis | 46+ | Application, upload, published theses | | Practice | 26 | External practice, documentation | | Erasmus | 15 | Applications, learning contracts | | Dormitory | 16 | Registration, periods, applications | | Final Exams | 15 | Periods, topics, applications | | MeetStreet | 70+ | Forums, news, events, votes, e-learning | | Bank Account | 17 | Manage payment accounts | | Publications | 18 | Academic publications | | User Profile | 29 | Settings, avatars, onboarding | | And more... | | Specializations, modules, registry sheets, legal remedies |

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)

| Tool | Description | |---|---| | get_student_info | Student profile, neptun code, training | | get_dashboard_data | GPA, credit progress, unread messages | | get_term_averages | GPA and credit index per semester | | get_all_grades | Grade for every subject across all terms (full transcript) | | get_subject_grade | Result/grade for one subject by ID | | get_taken_subjects | Subjects taken in a term | | get_exam_results / get_exam_results_terms | Exam results per term | | get_exams_list | Available exams for a subject in a term | | get_received_messages / get_message_detail | Read inbox / a thread | | get_calendar_events | Calendar events by date range | | get_financial_impositions / get_financial_payments | Fees and transactions | | get_pending_surveys / fill_all_surveys | Surveys (Playwright auto-fill) | | call_method / list_methods | Call/discover any of the 1,100+ API methods | | ...and more | Curriculum, documents, surveys |

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="JBSW…[redacted]")
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_USERNA

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars3
CategoryAutomation
Updated20d ago
Forks0

Languages

Python

Trust signals

87/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

2 low