@currikon/mcp

Model Context Protocol server for the Currikon curriculum API.

The package is API-backed and does not bundle the curriculum dataset. It connects to https://api.currikon.org by default and uses your Currikon API key for authenticated requests.

Install

Connector (recommended for Claude.ai and Claude Code) — the API serves an OAuth-protected remote MCP endpoint at /mcp; no install, no API key.

Claude.ai: Customize → Connectors → Add custom connector → https://api.currikon.org/mcp → Sign in.

Claude Code:

claude mcp add --transport http currikon https://api.currikon.org/mcp

Sign-in is via WorkOS AuthKit; the same ten tools below are exposed.

This package (servers, CI, scripts) — for anything that isn't Claude.ai or Claude Code, or that needs an API key rather than an interactive OAuth sign-in.

Claude Code:

claude mcp add -s user -e CURRIKON_API_KEY=ck_live_... currikon -- npx -y @currikon/mcp

Claude Desktop / Cursor:

{
  "mcpServers": {
    "currikon": {
      "command": "npx",
      "args": ["-y", "@currikon/mcp"],
      "env": {
        "CURRIKON_API_KEY": "ck_live_..."
      }
    }
  }
}

Use staging:

{
  "env": {
    "CURRIKON_API_KEY": "ck_live_...",
    "CURRIKON_API_BASE_URL": "https://staging-api.currikon.org"
  }
}

Tools

• get_status — dataset counts, jurisdictions, subjects
• search_competencies — explore: full-text search with facet counts (jurisdiction, school type, grade band, subject), matched terms and folded school-type variants; base-form words, all-words hits first; grade/schoolType filters; format: concise|detailed
• search_topics — explore the content vocabulary: full-text search over topics (Themen/Inhalte) such as Plasmolyse or Zahlenraum bis 100, each hit carrying the competency codes it teaches. Complements search_competencies: 22 % of topic names share no word with any competency sentence of the same slice. Topics exist for 10 of 21 jurisdictions (three quarters Bayern) — elsewhere an empty result is a data gap, not a finding. No facets; filter by jurisdiction and subject
• get_competency — fetch one competency by stable code
• list_competencies — filter by jurisdiction, subject, school type, grade; the complete band (limit 100) is the reliable path for one-Land lesson planning
• get_progression — prerequisites and successors for a competency
• find_equivalents — cross-jurisdiction equivalents
• list_frameworks — curriculum frameworks; one per source document, so a school type can list several (Sek I vs. gymnasiale Oberstufe)
• align_competencies — align free text to matching competencies
• align_batch — many texts × one Land → candidates per cell with a coverage report (2 credits per cell; call with dryRun: true first, it is free). Prefer grade over schoolType; jurisdiction aliases like NRW are accepted. Text-identical hits from other school types of the same Land are folded into the best match as variants (the limit counts distinct texts), and coverage reports sharedTextWith per framework so an agent can tell wortgleiche plans (NRW Sek I) from genuinely different ones. One Land/school type/subject can carry more than one framework (NRW Gymnasium Deutsch has a Sek-I and a gymnasiale-Oberstufe Kernlehrplan): each coverage framework may carry a stage (sek1 | gost | wp), and every sharedTextWith entry names its counterpart by frameworkId.

Changelog

0.2.6

• Ganze Sätze statt Fragmente. Kompetenzen tragen jetzt ein optionales Feld sentence: der wörtliche Vorspann des Lehrplans („Die Schülerinnen und Schüler können …") plus der verbatim Quelltext, mit Punkt. text bleibt die unveränderte Quellzeile. Alle Textzeilen der Werkzeuge (search_competencies, get_competency, get_progression, find_equivalents, align_competencies, align_batch) zeigen sentence, wenn es da ist, sonst text; structuredContent trägt text verbatim und zusätzlich sentence. Der Stamm ist nie erfunden: er wird als Zeile im eingefrorenen Quell-PDF nachgewiesen und nur dann vererbt, wenn der Satz grammatisch trägt (Server-PR #778, #779). Abdeckung: erster Schnitt Mecklenburg-Vorpommern (2.535 Sätze) und Bremen (5.439); weitere Länder folgen je Land. Ein Record ohne Stamm hat kein sentence. Reihenfolge: Server ist ausgeliefert, dann dieses Paket — ein 0.2.5-Client gegen den neuen Server läuft weiter, zeigt aber Fragmente.

0.2.5

• search_topics — die Themen (Inhalte) der Lehrpläne sind jetzt auch über MCP erreichbar, nicht nur über /v1/topics und /v1/search?type=topic. Ein Treffer nennt Name, Einordnung und die Kompetenzcodes, die das Thema unterrichtet. Warum ein eigenes Werkzeug statt eines Schalters an search_competencies: 22 % der Themennamen teilen kein Inhaltswort mit den Kompetenzsätzen desselben Schnitts (gemessen über alle 46.280 Themen, 2026-09-16) — „Plasmolyse" findet die Kompetenzsuche nie. Themen tragen außerdem keine Facetten und keine Varianten. Abdeckung: 10 von 21 Jurisdiktionen, drei Viertel davon Bayern. Das Werkzeug sagt es in seiner Beschreibung und bei jeder Fehlanzeige, damit eine Datenlücke nicht als Befund gelesen wird. Kosten: 2 Credits wie search_competencies — dieselbe Route, dieselbe Abrechnung, dieselbe Länderberechtigung. Reihenfolge: wie üblich erst den Server ausliefern, dann veröffentlichen. Ein kaputtes Fenster gäbe es hier zwar in keiner Richtung — type=topic beantwortet die Route seit Langem, und das Ausgabeschema schließt kein Objekt —, aber die Regel bleibt.

• query verlangt jetzt zwei Zeichen, in search_topics wie in search_competencies. /v1/search verlangt sie seit jeher (q min. 2); die Werkzeuge nahmen ein Zeichen an und ließen den Aufruf erst serverseitig mit 400 scheitern. Jetzt sagt es das Werkzeug selbst, bevor ein Credit fließt.

0.2.4

• Release order for this version is inverted: publish 0.2.4 to npm FIRST, then deploy the server. The usual rule is deploy-then-publish, but here the server adds a field (frameworkId) to an object that the already-published 0.2.3 declares as a closed schema, and the client validates structuredContent against that schema with Ajv — so every 0.2.3 install hard-fails align_batch from the moment the new server answers. 0.2.4 works against both the old and the new server, so shipping it first leaves no broken window.
• sharedTextWith entries carry a frameworkId. A jurisdiction/school type/subject triple can have more than one framework (NRW Gymnasium Deutsch: Sek I 2019 and gymnasiale Oberstufe 2022), so naming the counterpart by school type alone was ambiguous. This release is required against the current api.currikon.org: 0.2.3 derives a closed output schema and hard-fails align_batch on the new field.
• Coverage frameworks may carry a stage (sek1 | gost | wp), rendered in the framework listings. It is descriptive title material, not a filter — not every framework whose source names a stage carries one.
• No object in the align_batch and search_competencies output schemas is closed any more, the envelopes included. A new field on the server can no longer break an already-published client.

Local Development

npm install
npm --prefix packages/mcp run build
CURRIKON_API_KEY=ck_live_... npm --prefix packages/mcp run dev