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-apiIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AutomationSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| neptun-api (this skill)by IdrissaMaiga | 80 | 3 | 20d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | today | CLAUDE.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.
Skill content
View source on GitHubneptun-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
| 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
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
