How I Reverse-Engineered 1,100 Neptun API Endpoints

The Challenge#

Every Hungarian university student knows Neptun — the clunky but essential system for managing courses, exams, grades, and finances. Despite serving millions of students across dozens of universities, Neptun has no public API.

I decided to change that.

Reverse Engineering the Angular Client#

Neptun's web interface is built with Angular. By intercepting HTTP requests in Chrome DevTools, I mapped out the entire API surface. The Angular client communicates with a REST backend that exposes over 1,100 endpoints across 75+ controllers.

from neptun_api import NeptunClient

client = NeptunClient(
    base_url="https://neptun.uni-obuda.hu",
    username="your_neptun_code",
    password="your_password"
)

# Get all your grades
grades = await client.grades.get_all()

What the API Covers#

The wrapper provides typed access to 25+ functional areas:

• Messaging: 18+ methods for inbox, sent, compose
• Calendar: 29 methods for events and scheduling
• Courses: 60+ methods for enrollment and course data
• Exams: 30+ methods for exam registration and results
• Grades: 21 methods for academic records
• Financials: 50+ methods for tuition and payments

MCP Server Integration#

One of the most exciting features is the MCP (Model Context Protocol) server. This allows AI assistants like Claude and Cursor to interact with Neptun directly:

# Add to your Claude Desktop config
{
  "mcpServers": {
    "neptun": {
      "command": "python",
      "args": ["-m", "neptun_api.mcp_server"]
    }
  }
}

Key Technical Decisions#

1. Async-first: Built on httpx for async HTTP, making concurrent operations fast
2. Automatic JWT refresh: Transparent token management — no manual re-authentication
3. Playwright automation: For operations that require browser interaction (like surveys)
4. Multi-university support: Works with Obuda, BME, ELTE, and other Hungarian universities

Lessons Learned#

Reverse engineering taught me more about API design than any course could. You learn what makes a good API by studying a mediocre one.

The project is open source on GitHub and available via pip.