Sprachen — Multilingual Vocabulary Trainer with MCP Agent

A local, single-user vocabulary trainer with Leitner spaced repetition, domain/topic organization, and a ChatGPT MCP agent for lessons — plus optional OpenAI assistance in the app.

Project page

More background and write-up:

• Deutsch

• English

Related MCP server: GIM-MCP

Runs locally

This project is meant to run on your own machine (or local Docker). It is not a hosted SaaS, and there is no cloud/CDK deploy in this repo.

• Single-user, no login / no auth

• Data stays in a local SQLite file under data/

• Do not expose the app to the public internet without adding your own access control

Features

• Leitner 6-box spaced repetition

• Multiple languages (UI + vocabulary): German, English, Spanish, French, Portuguese, Swiss German

• Domains/topics for organizing entries

• Fuzzy answer matching (typo-tolerant)

• Conjugation practice

• Optional OpenAI-powered translation suggestions

• ChatGPT MCP at /mcp (persistence + review; AI stays in ChatGPT)

Quick start

Prerequisites

• Node.js 18+ and npm

• An OpenAI API key if you want AI features (optional for core review)

Initialize

git clone <this-repo-url>
cd sprachen

npm install
cp .env.example .env

Edit .env and set at least:

DATABASE_URL="file:../data/sprachen.db"
OPENAI_API_KEY=your_openai_api_key_here
NEXT_PUBLIC_NATIVE_LANG=de
# Optional — train only some targets (omit = all except native):
# NEXT_PUBLIC_TARGET_LANGS=en,es,fr

NEXT_PUBLIC_NATIVE_LANG is your mother tongue / source language (de | en | es | fr | pt | gsw). Set it once at install time.

NEXT_PUBLIC_TARGET_LANGS limits which languages you train (comma-separated). Example: en,es,fr for three languages only. Leave empty for all targets except your native language. Restart the app after changing it.

Create an empty SQLite database from the schema:

npm run db:push

Start the app:

npm run dev

Open http://localhost:4800.

npm run dev starts Next.js on port 4800 (MCP at /mcp) and the optional OpenAI MCP tunnel. Web only: npm run dev:web.

Environment

Copy from .env.example:

Never commit .env or .env.production — only .env.example is tracked.

Docker (optional, local)

No separate database container. SQLite lives in ./data:

export OPENAI_API_KEY=your_openai_api_key_here
npm run docker:up

App: http://localhost:4800.

ChatGPT MCP

Persistence MCP at /mcp (domains, entries, conjugations, review/Leitner, stats). Details for tunnel-client and ChatGPT Developer Mode: SETUP.md.

npm run dev          # app + tunnel (development)
npm run start        # app + tunnel (after npm run build)
npm run start:web    # production web only
npm run mcp:tunnel   # tunnel only

Voice Chat workaround

ChatGPT Voice Chat cannot call MCP tools directly. Use text MCP first, then voice, then sync back:

1. Load context in text chat — ask ChatGPT (with the MCP plugin enabled) to fetch the vocabulary / due cards / lesson context you need via MCP.

2. Start Voice Chat — continue in the same conversation so that context is already in the thread.

3. Practice by voice — train as usual; Voice Chat only talks, it does not write to the database.

4. Sync after voice — switch back to text and tell ChatGPT something like: „Okay, aktualisiere die Einträge basierend auf der Lehrer-Erfahrung.“ so it updates progress / entries through MCP.

Without that last step, the spoken lesson stays only in the chat history.

Leitner boxes

Cards move through 6 boxes with increasing intervals:

Correct → one box up. Wrong → back to box 1. Due cards have nextReviewAt in the past.

Tech stack

Next.js 15 · TypeScript · tRPC · SQLite + Prisma · Tailwind / shadcn/ui · OpenAI (optional) · Vitest

Development

npm run lint
npm run test
npm run build
npm run db:push
npm run db:studio

License

MIT — see LICENSE.