CLI and MCP

Use @sprachpass/cli from a terminal, @sprachpass/mcp with a local assistant, or @sprachpass/client in server-side TypeScript. All three packages are on npm at version 0.1.0. Real answer checks use the question-bank API and save no learner practice or history.

Install the CLI

Install Node 22.15 or newer, then install the CLI. The commands below use a POSIX shell, such as the macOS or Linux terminal, or Git Bash on Windows.

npm install -g @sprachpass/cli
sprachpass --help
sprachpass demo --json

The offline demo needs no API key or network access after installation. It covers seven synthetic response types. Its results are labelled synthetic and are not Sprachpass grades; its bundled media references are not live question URLs.

Connect your developer key

A learner subscription does not issue a developer key. With an issued key, run login in an interactive terminal and enter it at the masked prompt:

sprachpass login
sprachpass doctor --board goethe --json
sprachpass catalog --board goethe --json

In scripts, where no prompt can appear, pipe the key from your secret manager instead: sprachpass login --with-key-stdin. Login validates the key and stores it in the OS keychain. Linux needs persistent Secret Service. If keychain storage is unavailable, supply SPRACHPASS_API_KEY through your process environment or secret manager instead. It overrides a saved production key. Never put a key in command arguments, source files, or assistant chat.

Doctor checks health, authorization and quota without changing local settings. The catalogue reports currently eligible levels, parts, response types and counts. Use its results rather than guessing availability or question IDs.

List, fetch, and check one answer

1. 1List a small page of reading questions with the mcq_text response type.
2. 2Take an ID from that page and fetch the question using the same board.
3. 3Read the prompt and options, then save a response object using an option ID from response_schema.option_ids.
4. 4Send the response file to items check and read the returned correct boolean.

This example selects the first listed option to demonstrate the format. It is not an answer key. If the list is empty, inspect the catalogue and choose filters with eligible content.

sprachpass items list --board goethe --skill reading --response-type mcq_text --limit 3 --json > items.json
ITEM_ID=$(node -e 'const fs=require("node:fs"); const p=JSON.parse(fs.readFileSync("items.json","utf8")); if(!p.data?.length) process.exit(1); console.log(p.data[0].id)')
sprachpass items get "$ITEM_ID" --board goethe --json > question.json
node -e 'const fs=require("node:fs"); const q=JSON.parse(fs.readFileSync("question.json","utf8")); console.log(JSON.stringify({type:q.response_schema.type,selected_option_id:q.response_schema.option_ids[0]}))' > response.json
sprachpass items check "$ITEM_ID" --board goethe --response-file response.json --json

{ "correct": false }

An incorrect answer is a successful check and exits 0. The API returns no answer key or explanation. Remove the three scratch JSON files when finished. The walkthrough makes four requests: list, get, then get and check. Only continue after each command succeeds.

Board is required for catalogue, list, get and check: goethe or telc. CLI skills accept reading/listening or lesen/hoeren. Lists default to one page of 25, with limit from 1 to 100. To fetch another page, pass pagination.next_cursor as --cursor with every filter, including limit, unchanged. A null cursor means the list is exhausted.

Output and exit codes

Results go to stdout. Use --json for one JSON document; pipes default to JSON. Human error diagnostics use stderr. Machine errors include error.code and may include request_id, retry_after and rate_limit. CLI, REST and MCP share the developer client's quota.

Exit | Meaning                          | Next step
0    | Success, including a wrong answer | Read correct, not only the exit code.
2    | Usage or input validation        | Check --help and the response schema.
3    | Credential or keychain problem   | Supply a valid key or restore keychain access.
4    | Forbidden or suspended client    | Contact Sprachpass about access.
5    | Question not found               | List again on the same board.
6    | Rate limited                     | Wait retry_after seconds or until reset.
7    | Network, timeout, redirect       | Check connection and the intended API URL.
8    | Server or invalid response       | Retry later; report the request ID if repeated.
9    | Conflict (learner practice)      | Read error.code; a saved answer is final.
130  | Cancelled                        | Resume from the last successful checkpoint.

Practise as a learner

From CLI version 0.2.0, a learner can practise Hören and Lesen from the terminal and save each run to their own Sprachpass account. It uses the learner's own sign-in, not a developer key: the practice commands never read or send an API key. Runs count against the same daily allowance as the website and appear in History.

sprachpass learner login
sprachpass practice access
sprachpass practice start --board goethe --level A1 --skill lesen
sprachpass practice answer SESSION_ID --position 0 --response '{"type":"true_false","value":true}'
sprachpass practice complete SESSION_ID
sprachpass practice history

1. 1Run learner login. Your browser opens the Sprachpass sign-in and approval page; approve the Sprachpass CLI. In a terminal without a browser, add --no-browser and open the printed link yourself.
2. 2Run practice access to see your exam, plan and runs left today.
3. 3Start a run. The CLI shows the session ID and the first question with its response_schema.
4. 4Answer each position with --response (a JSON object in the response_schema shape) or --skip. Each answer shows the verdict, the explanation, the correct response and the next question.
5. 5After all ten answers, run practice complete, then practice history to see the saved run.

The API alone grades each answer. If a command is interrupted, run the same command again: it reuses the same request key, so the answer is saved once and the output says replayed: true. When the daily limit is reached the CLI exits 6 and shows when it resets. learner logout removes the sign-in from this computer; Connected apps in your Sprachpass account ends access everywhere.

Connect local MCP

The MCP server runs locally over stdio and needs Node 22.15 or newer. Configure your assistant to launch npx with arguments ["-y","@sprachpass/mcp"] and supply SPRACHPASS_API_KEY to the server process. The equivalent launch command is:

npx -y @sprachpass/mcp

Generate the configuration for your client. Each command prints only: it reads no saved key and edits no client settings. Without --json, stdout is the pasteable JSON or TOML; --json adds the target path and setup instructions.

sprachpass mcp config --client claude-desktop --command npx --args '["-y","@sprachpass/mcp"]'
sprachpass mcp config --client claude-code --command npx --args '["-y","@sprachpass/mcp"]'
sprachpass mcp config --client cursor --command npx --args '["-y","@sprachpass/mcp"]'
sprachpass mcp config --client codex --command npx --args '["-y","@sprachpass/mcp"]'

• Claude Desktop: open Settings > Developer > Edit Config and merge the server entry. Its literal key placeholder needs private local replacement, or remove env and arrange an inherited process environment. Do not assume Desktop expands the placeholder.
• Claude Code: merge the JSON into project .mcp.json; its placeholder references SPRACHPASS_API_KEY from the client environment.
• Cursor: merge the JSON into project .cursor/mcp.json or your user MCP configuration; its placeholder uses the client's environment-reference syntax.
• Codex: merge the TOML into $CODEX_HOME/config.toml, default ~/.codex/config.toml. env_vars forwards SPRACHPASS_API_KEY without storing its value.

Keep other server entries when merging. GUI apps may need absolute executable paths because their PATH and environment can differ from your terminal. Restart the client after setup. MCP reads its environment at startup and does not read the key saved by CLI login; restart it after a key change.

Use the four tools

• sprachpass_get_catalog: live levels, skills, parts, response types and counts for the chosen board.
• sprachpass_list_questions: one small page, default 5 and maximum 25, with optional filters and explicit cursor pagination.
• sprachpass_get_question: one returned ID's prompt, options, response schema and optional media URL.
• sprachpass_check_answer: send the structured response and receive the API's correct boolean. A false result is a successful call.

Every tool needs board. Use lesen or hoeren in MCP tools; part also requires level. Ask your assistant to read the catalogue, list up to five questions, fetch one returned ID, present it, collect your response and call the check tool. Successful results have structuredContent.data and error set to null; failures provide error.code and error.recovery. Keep request_id for support and wait when retry_after is returned.

Practise as a learner with MCP

From MCP version 0.3.0, the server has a learner mode, so your assistant can run your saved Hören and Lesen practice and save each run to your own Sprachpass History. It uses the learner sign-in from the CLI, not a developer key, and never reads or sends SPRACHPASS_API_KEY. Sign in once with the CLI, then launch the server with --learner and no key:

sprachpass learner login
npx -y @sprachpass/mcp --learner

• sprachpass_get_access: your plan, the exams you can practise, runs left today and open runs. Saves nothing.
• sprachpass_start_practice: start a ten-question run for a board, level and skill, or resume the open one. Saves the run.
• sprachpass_get_practice: the run, your answered verdicts and the next question. Saves nothing.
• sprachpass_submit_answer: save one answer; returns the verdict, explanation, correct response and next question.
• sprachpass_complete_practice: finish after ten answers; returns the score and saves the result to History.
• sprachpass_list_history and sprachpass_get_result: your completed runs and one run's answers. Save nothing.

Sprachpass decides every verdict and score. Retrying the same answer or completion returns the saved result with replayed: true, so nothing is saved twice. Runs count against the same daily allowance as the website. When the sign-in has ended, run sprachpass learner login and restart the server. The hosted server at https://sprachpass.com/mcp offers the same practice tools to assistants that connect with your Sprachpass sign-in.

Use the TypeScript client

For a server integration, install @sprachpass/client. It needs Node 20 or newer with native fetch. Pass the environment key explicitly; the client does not read environment variables itself.

npm install @sprachpass/client

import { createPublicApiClient } from '@sprachpass/client';

const api = createPublicApiClient({ apiKey: process.env.SPRACHPASS_API_KEY });
const page = await api.listItems({ board: 'goethe', skill: 'lesen', response_type: 'mcq_text', limit: 3 });
const item = page.data.data[0];
if (!item || item.response_schema.type !== 'mcq_text') throw new Error('No multiple-choice question returned');
const verdict = await api.checkItemResponse(item.id, {
  board: item.board,
  response: { type: 'mcq_text', selected_option_id: item.response_schema.option_ids[0] },
});
console.log(item.id, verdict.data.correct, verdict.requestId);

This also selects the first option only as a format example. Client results include data, requestId and rateLimit. Keep keys on your server.

Tested with: 24 October 2026

Version 0.1.0: clean package installation, CLI demo and MCP stdio checks passed in CI on macOS, Linux and Windows with Node 22. Published CLI command help, offline JSON demo and configuration generation for all four clients were checked on macOS. Earlier macOS checks used Node 22.23.2, pnpm 10.9.0 and MCP SDK 1.32.1: the Desktop-format JSON entry launched with the SDK and listed four tools using a synthetic key; Codex 0.163.0 loaded generated TOML in a temporary configuration home.

These are SDK and configuration checks. Claude Desktop, Claude Code and Cursor app sessions, inline audio playback, and an authenticated assistant conversation were not tested.