LingoChunk MCP

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-mcp in Claude Code (server plus lesson skills), or npx -y @lingochunk/mcp as a standalone MCP server.

What it gives an agent

Twelve tools, each wrapping one public endpoint. The first seven are read-only; the last five write to your account.

Plus three skills:

• 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-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.

Related MCP server: Levelang MCP Server

Prerequisites

• 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 and lessons: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.

Use it

Option A - Claude Code plugin (the server plus the lesson skills)

This repo is its own plugin marketplace. In Claude Code:

/plugin marketplace add lingochunk/lingochunk-mcp
/plugin install lingochunk@lingochunk-mcp

The 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_here

The skills/ (lesson builder and episode discussion) are picked up automatically with the plugin.

Option B - standalone MCP server (tools only, no skills)

claude mcp add --scope user lingochunk --env LINGOCHUNK_TOKEN=lcp_... -- npx -y @lingochunk/mcp

For 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.js

Use with other agents

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):

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.

Updating and checking versions

Two artefacts ship from this repo and version separately:

Update the plugin (Claude Code)

/plugin marketplace update lingochunk-mcp
/reload-plugins

The 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 --available

Set-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.

Update the MCP server

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, relaunch

Or 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.

Configuration

The token is only ever sent as an Authorization: Bearer header to the configured origin; it is never written to disk or logged.

Building a lesson

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/.

Repository layout

src/                                    the MCP server (TypeScript, stdio)
skills/lingochunk-lesson/               the coursebook lesson skill
skills/lingochunk-cards/                the flashcard (card.v1) skill
skills/lingochunk-discuss/              the "discuss an episode" skill
skills/*/examples/                      example lesson.v1 documents (CI-validated)
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 plugin

Contributing a skill

Skills 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.

Development

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 0db02377.

Live smoke test

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.ts

License

MIT.