Summary: Read your LingoChunk vocabulary, library, transcripts and native audio, then add flashcards, export Anki decks and save lessons.
Vocabulary — get_vocabulary lists your words aggregated with FSRS maturity (known/learning/new/due), filterable by language, status, CEFR, with since+cursor incremental sync; lookup_word returns one word's own context (translation, gender, CEFR, FSRS state) with a shared-lexicon fallback.
Library & transcripts — list_library pages your ready-to-study episodes; get_transcript returns timestamped sentences with translations, sliceable by sentence or time range.
Audio — get_audio_url gives a short-lived presigned URL to the full native audio (Range-capable); get_audio_clip cuts and saves a local ≤60s snippet for embedding in lessons.
Example sentences — search_examples finds sentences by lemma or case-insensitive substring q, restricted by language (capped sample).
Flashcards — list_decks shows your decks with counts; add_card adds an FSRS card (existing vocabulary word or freeform front/back, optionally anchored to a transcript sentence and deck).
Allows exporting Anki decks from LingoChunk vocabulary and adding review cards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@LingoChunk MCP look up 'perro' in my vocabulary"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server (and Claude Code plugin) that turns a coding agent into a language tutor grounded in your own LingoChunk listening history: your FSRS-graded vocabulary, native-audio transcripts and clips, and your library.
It is a thin client over the LingoChunk public API (/api/v1): read-only tools
for your vocabulary, transcripts and audio, plus write tools to add review cards,
export Anki decks and save lessons. The app stays closed source; this repo is
the client, the committed API spec, and the skills - and the skills are open to
contributions (see CONTRIBUTING.md).
Install:
/plugin marketplace add lingochunk/lingochunk-mcpin Claude Code (server plus lesson skills), ornpx -y @lingochunk/mcpas a standalone MCP server.
A creator rather than a coder? If you make audio (a podcast, a YouTube channel, classes) and want your episodes to become annotated transcripts, lessons, courses and multi-language study guides your audience can use, start with LingoChunk for creators - no programming required, everything happens by talking to an AI assistant.
Forty tools. Nineteen read from your account; nineteen write to it; two serve
guidance: whats_possible answers "what can I do here?" with a short menu
and an example prompt per area, and get_authoring_guide serves the full
authoring craft guides so remote clients that never see the skills still
compose good lessons, cards and annotations.
Tool | Scope | What it does |
| none | The quick tour: every area this connection covers (discuss, vocabulary, lessons, courses, cards, languages, creator notes, publishing), one example prompt each. The agent answers short and offers to go deeper per area. |
|
| Your vocabulary, aggregated per word with FSRS maturity (known/learning/new/due). Filterable; incremental sync via |
|
| One word: your own context plus a shared-lexicon gender/CEFR fallback. Grounds an LLM's guesses. |
|
| Your ready-to-study episodes (own + followed collections), cursor-paginated. |
|
| A submission's timestamped sentences + translations, sliceable by sentence or time range. |
|
| A short-lived presigned URL to the full native audio (Range-capable). |
|
| Example sentences across your library, by word ( |
|
| Cuts a short native-audio snippet, saves it to a local file, and returns |
| none | Returns the full craft guide for |
|
| Your study decks with card counts, for picking a |
|
| Adds a card to your review queue (FSRS, starts new). Preferred: the |
|
| Exports a deck to Anki |
|
| Dry-run validates a |
|
| Saves a lesson to your private library (100 max). Preferred: a structured |
|
| Your saved lessons, newest first (id, title, language, format, source episode, and |
|
| Reads back a saved |
|
| Revises a saved |
|
| Permanently deletes one saved lesson by id (destructive; owner-scoped server-side). For lessons the user is done with - revision is |
|
| Creates a course: a named, ordered series to file lessons under. Returns its id, for |
|
| Your courses, newest first, each with its lesson count - for finding a |
|
| Deletes one course by id (destructive to the grouping, idempotent). Its lessons SURVIVE - their |
|
| An episode's target languages and how to add more: the fan-out group so far (each with its own submission id + status), |
|
| Pages the primary's sentences to translate yourself: source text, the pivot-language gloss per sentence and per token (which fixes each word's sense). Feeds the draft flow. Empty glosses throughout mean a bare episode, awaiting a cold fill. |
|
| Fans an episode out into 1-10 extra ordinary target languages server-side (Groq, no tokens of yours); returns a job per language. Leveled same-language codes are rejected here - use the draft flow. |
|
| Uploads a batch (1-100) of agent-written draft sentences (whole-sentence translation + one meaning per token) for a target or leveled language; returns per-sentence rejections to repair. Targeting a bare episode's OWN language is the cold fill, and takes optional per-token |
|
| Validates a complete draft and applies it, minting the sibling deck; polls the job and returns the new submission id when ready. A cold fill applies in place instead - no sibling, no language slot - and un-bares the episode. |
|
| Deletes the in-progress draft rows for a language (destructive; never a committed sibling). |
|
| Everything needed to translate ONE lesson into one language: its meta-language strings as path-addressed units (each |
|
| Saves your translated units as a language EDITION of the lesson on the sibling submission - target text, structure and answers stay byte-identical by construction. A 400 lists every problem at once; |
|
| The same for a whole lesson path: the plan's units plus per-section state ( |
|
| Mints the sibling's lesson-path plan from the master's translated plan units - once, before any section. Structure (positions, order, focus, minutes) is copied server-side. |
|
| Attaches ONE translated lesson-path part to the sibling's plan, keyed by the section's |
|
| An episode's creator annotations (each a markdown note on a transcript sentence span), plus |
|
| Attaches a markdown creator note to a sentence span (Unicode code-point offsets into the sentence's |
|
| Replaces one annotation's note in place (the anchor stays put). |
|
| Deletes one annotation (destructive); also how you fix a mis-anchored span before re-creating it. |
|
| Starts (or reports) the server-side plan for a lesson path over an episode: the sections, their sentence ranges and their teaching focus. Poll it; calling twice while one is in flight is safe. |
|
| The current lesson path: plan status, every section with its bounds, focus and whether a part has been written for it yet. |
|
| Returns the runtime brief for the next unwritten section: the sentences, the target vocabulary, the audio windows and the pedagogy this part must follow (optionally for a named teaching |
|
| Submits the written part back against its brief (pass the same |
Renamed in 0.14.0. The guided page is retired and the Lessons tab is the
one learner path, so the path tools carry lesson-path names. The old names are
still registered as deprecated aliases of the same endpoints and will be
removed in a future release; the guided:read / guided:write scopes are
unchanged, so existing tokens keep working.
Deprecated alias | Use instead |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Plus nine skills:
lingochunk-overview - the "what can I do?" tour: a short menu of
every area (with an example prompt each) and instructions to answer
briefly, then expand whichever area the user picks.
lingochunk-lesson - composes a coursebook-style lesson.v1 document
(listen, text, vocabulary, one grammar point, graded exercises, review)
from the tools above, filtering out words you already know; the app
renders it natively and can export an offline HTML worksheet.
lingochunk-course - plans a multi-lesson series: slices an episode (or
collection) into coherent parts, creates a course, then builds N lessons via
the lesson skill with a different grammar point and ramping difficulty per
lesson, each filed under the course in order.
lingochunk-guided - writes the parts of a lesson path yourself,
following the plan-brief-compose-submit loop, so they render exactly like
internally generated ones. It teaches only the loop: the pedagogy for each
part arrives inside its brief at runtime.
lingochunk-cards - builds native-grade flashcards with the card.v1
kinds: verbatim transcript anchors, per-kind guidance (grammar =
production cloze of the morpheme with a hint), and a quality rubric
distilled from the known failure modes of AI-generated cards.
lingochunk-discuss - a lighter, conversational "talk me through this
episode" workflow.
lingochunk-add-language - adds another language to one of your episodes
as a new sibling deck: either the server-side Groq fan-out for an ordinary
target, or an agent-supplied translation you write sentence by sentence and
commit - the only way to build a leveled same-language deck (e.g.
"German (A2)", German audio glossed in simpler A2 German). It also covers
the cold fill: finishing an episode processed without the server's AI,
by writing its word meanings yourself in its own language.
lingochunk-annotate - finds the genuinely useful expressions in one of
your episodes (idioms, phrasal verbs, collocations, discourse markers,
culture-bound references) and attaches a short markdown creator note to each
exact span: an iris tint + note sheet for you, a forward-only note card for
your followers.
lingochunk-skill-author - the meta-skill: generalises a lesson you
have refined (say, through the app's Co-edit mode) into a NEW reusable
skill - structure and voice kept, episode content replaced by
fetch-and-quote instructions - which you keep private in your own AI's
context or contribute here as a PR (see CONTRIBUTING).
The Claude Code plugin installs these as skills. Every client also gets the
same guidance two other ways that need no plugin: as MCP prompts (one per
skill, named lingochunk-lesson, lingochunk-cards, ...) in the client's
prompt/slash picker, and via the get_authoring_guide tool the model can
call itself before composing.
Related MCP server: atomicreps
Node.js >= 18.
A LingoChunk personal access token: in LingoChunk, open Settings -> API
access, create a token, and grant the scopes you need (vocab:read +
content:read cover the read tools; add cards:write, decks:export,
lessons:write, translations:write and annotations:write for the write
tools). The token is shown once and starts with lcp_. The 403 errors from
the tools name the exact scope you are missing.
This repo is its own plugin marketplace. In Claude Code:
/plugin marketplace add lingochunk/lingochunk-mcp
/plugin install lingochunk@lingochunk-mcpThe plugin's .mcp.json runs the published server via npx, pinned to the
exact version the plugin was released with (no build step needed), and reads
your token from the environment, so export it in the shell you start Claude
Code from:
export LINGOCHUNK_TOKEN=lcp_your_token_hereThe skills/ (lesson builder and episode discussion) are picked up
automatically with the plugin.
claude mcp add --scope user lingochunk --env LINGOCHUNK_TOKEN=lcp_... -- npx -y @lingochunk/mcpFor development against a local checkout, run the built server directly:
npm install # installs deps and builds dist/ via the prepare script
claude mcp add lingochunk --env LINGOCHUNK_TOKEN=lcp_... -- node /absolute/path/to/lingochunk-mcp/dist/index.jsThe same server also runs hosted at https://lingochunk.com/mcp as a
standard remote MCP server (Streamable HTTP). Nothing to install - paste
the URL into any client that supports custom remote MCP servers and sign in
with your LingoChunk account when the client prompts you (OAuth 2.1 with a
consent screen; the grant appears in Settings -> API tokens, revocable like
any token). Clients with a token field can instead send a personal access
token as a Bearer credential:
Client | Where |
claude.ai (web/desktop/mobile, incl. Free) | Settings -> Connectors -> Add custom connector -> URL |
Claude Code |
|
ChatGPT (paid plans) | Settings -> enable Developer mode -> Apps -> "+" -> URL (OAuth), or URL + your token |
Mistral Le Chat | + Add Connector -> Custom MCP Connector -> URL (auth auto-detected) |
Perplexity (Pro/Max), Grok, Manus | add a custom connector/MCP server by URL, sign in or paste an API key |
Differences from the local server: get_audio_clip is unavailable (it writes
files, which only makes sense on your own machine - use get_audio_url), and
skills don't auto-load (the server exposes each skill as an MCP prompt,
and agents can pull the same guidance through the get_authoring_guide tool).
If your client offers neither OAuth nor a token field, embed the token in
the URL: https://lingochunk.com/mcp/t/lcp_.... That URL then IS a
credential - treat it like a password, prefer a token with only the scopes you
need, and revoke it in Settings if it ever leaks. OAuth sign-in or a header,
when your client supports one, is always preferred (URLs end up in access
logs).
Nothing in the server is Claude-specific: it is a standard stdio MCP server,
so any MCP-capable agent can run it. The recipe is always the same - run
npx -y @lingochunk/mcp with LINGOCHUNK_TOKEN in its environment - and
most clients express it as JSON like this:
{
"mcpServers": {
"lingochunk": {
"command": "npx",
"args": ["-y", "@lingochunk/mcp"],
"env": { "LINGOCHUNK_TOKEN": "lcp_your_token_here" }
}
}
}Where that config lives per client (differences noted):
Client | Where |
Claude Desktop | Settings -> Developer -> Edit Config ( |
Cursor |
|
Windsurf |
|
VS Code (Copilot agent mode) |
|
Gemini CLI |
|
Codex CLI |
|
Where your client supports it, prefer referencing an environment variable
over pasting the token into the config file (VS Code can prompt for it via
inputs; CLI clients usually inherit your shell environment).
The skills are not Claude-specific either: each one is a plain-markdown
playbook (skills/<name>/SKILL.md). Claude Code auto-loads them through the
plugin; with any other agent, point it at the file (or paste it as context)
and ask for a lesson. Every hard guarantee - the schema, verbatim transcript
quoting, sentence positions - is enforced server-side on save, so the
quality contract holds no matter which agent is driving.
Two artefacts ship from this repo and version separately:
Artefact | Carries | Check the version with |
Claude Code plugin | the skills + the server launcher |
|
npm package | the MCP server (the tools) |
|
/plugin marketplace update lingochunk-mcp
/reload-pluginsThe first refreshes the marketplace; the second activates updated skills in the RUNNING session (new sessions load them automatically). To compare the installed version against what the marketplace offers:
claude plugin list --json --availableSet-and-forget alternative: /plugin -> Marketplaces -> select
lingochunk-mcp -> Enable auto-update (third-party marketplaces have it
disabled by default; official ones are on). With it enabled, Claude Code
refreshes at startup and prompts /reload-plugins when something changed.
An update only appears when the plugin's version was bumped - Claude Code
uses it as the cache key, which is why our release rule (CONTRIBUTING.md)
bumps it on every user-visible change.
The plugin pins the exact server version in its .mcp.json, so updating
the plugin updates the server too - no separate step. A running session
keeps its old server process; /reload-plugins (or a new session)
reconnects to the new one.
Standalone installs (claude mcp add ... npx -y @lingochunk/mcp, or the
other-agents configs above) are exposed to an npx trap: npx caches packages
in ~/.npm/_npx and does NOT re-check the registry once cached, so an
unpinned @lingochunk/mcp can run a stale server indefinitely. To check and
fix:
npx -y @lingochunk/mcp --version # what npx actually runs
npm view @lingochunk/mcp version # latest published
rm -rf ~/.npm/_npx # blunt fix: clear the npx cache, relaunchOr make your config always-fresh by using @lingochunk/mcp@latest (checks
the registry on every launch: ~1-3 s extra startup and a registry
dependency), or pin @lingochunk/mcp@<version> and move the pin yourself
when you want the update.
Variable | Required | Default | Meaning |
| yes | - | Your personal access token ( |
| no |
| API origin override (for self-host/testing). |
| no |
| Where |
The token is only ever sent as an Authorization: Bearer header to the
configured origin; it is never written to disk or logged.
Every lesson-path tool 404s while other tools work. That surface is
gated behind the lesson_production_enabled account flag. It moved there
from guided_lessons_enabled when the guided page was retired, so a
previously working account can start 404ing without the token changing.
A tool 403s naming a scope. Mint a token that includes it (LingoChunk ->
Settings -> API tokens). The one exception is pack_admin_only, which is a
reserved teaching pack rather than a missing scope - drop the pack
argument instead.
node dist/index.js --http serves the same tools over Streamable HTTP for
remote MCP clients (see Option C). The process is stateless and multi-user:
LINGOCHUNK_TOKEN is not read - every request must carry its own
Authorization: Bearer lcp_... header, which is forwarded verbatim to the
API (the API stays the sole authority; the server stores nothing). A
Dockerfile is included.
Variable | Required | Default | Meaning |
| no |
| Listen port ( |
| no |
| API origin; co-located deployments should point at the loopback origin. |
Endpoints: POST /mcp (the MCP wire), GET /health (liveness).
Ask your agent something like "build me a lesson from yesterday's German episode"
or "quiz me on the words I'm learning". The lingochunk-lesson skill drives the
workflow: pick the source, pull a transcript slice, gather and filter your
vocabulary (never quizzing you on mastered words), then compose a structured
lesson.v1 document that the app renders natively - real episode audio, live
word state, crosslinks, Ask AI - with an offline HTML export available in-app.
A submission can hold many lessons, so different skills (or repeated runs) add
lessons side by side under the episode's Lessons tab. See
skills/lingochunk-lesson/.
src/ the MCP server (TypeScript, stdio)
skills/lingochunk-overview/ the "what can I do?" tour skill
skills/lingochunk-lesson/ the coursebook lesson skill
skills/lingochunk-course/ the multi-lesson course planner skill
skills/lingochunk-guided/ the lesson-path writer-loop skill
skills/lingochunk-cards/ the flashcard (card.v1) skill
skills/lingochunk-discuss/ the "discuss an episode" skill
skills/lingochunk-add-language/ the add-language / draft-translation / cold-fill skill
skills/lingochunk-annotate/ the useful-expression annotation skill
skills/lingochunk-skill-author/ the meta-skill: lesson -> reusable skill
skills/*/examples/ example lesson.v1 documents (CI-validated)
docs/creator-guide.md the guide for content creators (start here if you make audio)
docs/skill-authoring.md how to write a new skill
docs/skill-template.md SKILL.md starting point
docs/integrations/fluent.md how to plug this into the fluent tutor plugin
spec/openapi-public-v1.json the committed public API spec (the contract)
scripts/validate-lesson.ts validate a lesson.v1 document against the spec
scripts/smoke.ts live smoke test (run by hand, never in CI)
test/ vitest unit tests (mocked fetch) + example validation
.claude-plugin/plugin.json Claude Code plugin manifest
.mcp.json MCP server definition for the pluginSkills are markdown pedagogy, not code: a SKILL.md playbook plus an example
lesson.v1 document that CI validates against the committed spec. Anyone can
contribute one - a dictation drill, an exam rehearsal, a due-words review
session - and AI-drafted skills are explicitly welcome. Start with
CONTRIBUTING.md and
docs/skill-authoring.md.
npm install # deps + build (prepare)
npm run build # compile src/ -> dist/
npm run typecheck # type-check without emitting
npm test # vitest unit tests (mocked fetch; no network) + skill example validation
npm run validate:lesson -- <doc.json> # validate a lesson.v1 document (Node 22.6+)spec/openapi-public-v1.json is the source contract; it is exported from the
LingoChunk repo (make generate-openapi-public) and refreshed here on each API
release. This copy was taken from LingoChunk commit 37868242.
scripts/smoke.ts exercises a real API and is not part of npm test. Build
first, then run it by hand with a real token:
npm run build
LINGOCHUNK_TOKEN=lcp_... [LINGOCHUNK_BASE_URL=http://localhost:8000] \
node --experimental-strip-types scripts/smoke.tsMIT.
Add a card to the user's LingoChunk review queue (FSRS; it starts as 'new'). kind=vocab adds a word the user ALREADY has in their vocabulary, resolved by lemma against their own content (404 if the lemma is not in their vocabulary; 409 code=ambiguous_lemma if it occurs in several episodes or under several parts of speech, so pass submission_id or pos as the message names). kind=custom adds a freeform card and REQUIRES front, back and submission_id (the episode it anchors to); pass sentence_position to anchor its example to a specific transcript sentence. Omit deck_id and the card goes to the deck for its own submission (the same deck the app builds, reviews and exports that episode from, so it is immediately visible and exportable); an explicit deck_id must belong to that submission (400 otherwise). A 409 code=duplicate_card means the card already exists: expected, not worth retrying. NOTE: deleting the anchoring episode deletes the card (cascade), and a card added while the app's Words tab is open on that episode may be overwritten by the app's own save, so add cards when the app is not actively editing that deck. Requires the cards:write scope.
Inputs: kind (required), pos, back, note, +5 more.
Export one of the user's decks to an Anki .apkg and return a download URL. Running it costs nothing (no LLM). This starts the export and polls status for up to ~60s, absorbing rate limits with a Retry-After backoff and never starting a second job while one is already in flight. It returns {status:'ready', download_url} when the file is ready, {status:'pending'} (call again shortly to keep checking) while it generates, {status:'failed'} to retry, or {status:'none'} (nothing to download; call again to trigger a fresh export). A deck with no linked source episode cannot be exported (400). Use list_decks to find a deck_id. Requires the decks:export scope.
Inputs: deck_id (required).
Cut a native-audio snippet [start, end] (seconds, max 60s) from a submission and SAVE IT to a local file, returning the file path. Use these small clips to embed audio in a self-contained HTML lesson (e.g. as a data URI). Rate limited.
Inputs: end (required), start (required), submission_id (required).
Get a short-lived presigned URL to a submission's full native audio (supports HTTP Range). Use for streaming; for a durable snippet to embed in a lesson, use get_audio_clip instead.
Inputs: submission_id (required).
Fetch a submission's transcript: timestamped sentences with translations. Sliceable by sentence-position range (from_sentence/to_sentence) or time range in seconds (from_time/to_time) so you can pull an excerpt instead of a whole episode. transcript_state tells you if it is ready, still processing, or unavailable.
Inputs: submission_id (required), to_time, from_time, to_sentence, +1 more.
List the user's vocabulary, aggregated per word with FSRS maturity (state/stability/due/reps). Grounded in the user's real listening history. Filter by language, status (known|learning|new|due), or CEFR; use 'since' (an ISO 8601 time from a prior 'updated_at') plus 'cursor' for incremental sync. Sync is additive-only, so full-resync periodically. The list is cursor-paginated (limit up to 200); follow next_cursor until it is null to read the complete set.
Inputs: cefr, limit, since, cursor, +2 more.
List the user's study decks so you can pick a deck_id before adding cards (add_card) or exporting (export_anki_deck). Each deck reports its language and card counts (total / new / due). Requires the cards:write or decks:export scope.
Inputs: no named parameters.
List the user's ready-to-study episodes (their own submissions plus collections they follow), newest first. Cursor-paginated. Use the returned submission ids with get_transcript / get_audio_url / get_audio_clip.
Inputs: limit, cursor.
Look up one word: the user's own context (translation, gender, CEFR, FSRS state) if they have cards for it, backed by the shared enrichment lexicon as a gender/CEFR fallback. Use this to ground an LLM's guesses about a word rather than inventing them.
Inputs: lemma (required), language (required), pos.
Save a single self-contained HTML lesson to the user's private LingoChunk library (10 MB max, up to 100 lessons, private by default). Returns the lesson metadata plus a short-lived view URL to open it now; its durable home is the app's library, where it opens on any device. Use this to keep a lesson the lingochunk-lesson skill produced. Requires the lessons:write scope.
Inputs: html (required), title (required), language (required), source_submission_ids.
Search the user's readable library for sentences. 'lemma' returns the curated example sentences for that word; 'q' does a case-insensitive substring match on sentence text. At least one is required, and 'lemma' takes precedence when both are given. Results are a capped sample, not exhaustive.
Inputs: q, lemma, limit, language.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 11 tools
Each tool serves a distinct purpose: card management, export, audio, transcripts, vocabulary, decks, library, lessons, and search. There is clear differentiation even for similar operations like get_audio_clip vs get_audio_url (snippet vs stream) and get_vocabulary vs lookup_word (list vs single word with context).
All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_card, get_audio_clip, list_decks, lookup_word). No mixed conventions or ambiguous verbs.
With 11 tools, the server covers essential functionalities for a language learning app without being excessive. Each tool has a clear role and contributes to a coherent workflow.
The tool surface covers core operations: card addition, export, audio retrieval, transcript access, vocabulary management, and lesson saving. Minor gaps exist (e.g., no explicit card update/delete tool), but the set is functional for the intended use case.
Turn any recording or document into notes, flashcards and quizzes your agent can read and act on
Free: turn your AI chats into spaced-repetition vocabulary. 13 tools, reads and writes.
Lexpad is a vocabulary notebook with spaced repetition, in 81 languages. Connect it to ChatGPT or Claude and ask the assistant to save a word from your chat, show the words due today or quiz you. Each answer counts as practice and moves the word through its Leitner boxes. Sign-in is OAuth 2.1 with PKCE on a Lexpad page. 20 tools; the ones that overwrite or delete are marked, so the client asks first. Connecting is free. On Lexpad's Free plan the assistant writes 10 cards a day; on Pro it is unlimited, up to 1,000 a day. Guide and example prompts: https://lexpad.app/features/assistants
Co-Learn with your Agent: fact-checked AI lessons with Human and Agent views.
