learning-tool-mcp
Learning Tool MCP is a local, single-user study server that turns PDFs into flashcards and quizzes, grades answers, and schedules spaced repetition with SM-2.
Ingest PDFs and store their text as study material (
ingest_material).List and retrieve documents with ids, titles, and item counts (
list_documents,get_material,get_study_items).Save host-generated flashcards and quiz questions (
save_flashcards,save_quiz).Review due items sorted by SM-2 schedule, with an interactive study widget in supporting hosts (
get_due_items).Submit answers with automatic grading for quizzes and self-reported results for flashcards, plus optional confidence levels (
submit_response).Track progress with mastered, to-review, in-progress, remaining, and confidence breakdowns (
get_session_state).Export study items to Anki-importable CSV (
export_document).Delete documents or reset progress (destructive actions, confirm first).
Exports study items to an Anki-importable CSV file so users can import flashcards into Anki with File → Import.
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., "@learning-tool-mcp Turn my photosynthesis PDF into flashcards and quiz me"
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.
Learning Tool MCP
An MCP server that turns your own PDFs into flashcards and quizzes, grades your answers, and schedules reviews with the SM-2 spaced-repetition algorithm.
Single user, fully local, no accounts, no network calls, no database: your study material lives in a directory of JSON files on your machine.
How it works
The server contains no LLM and calls none. The MCP host you are already talking to is the language model, so it writes the study items; the server does the parts a model is bad at: durable storage, exact grading, counting, and scheduling.
your PDF
|
| ingest_material parse + chunk
v
+----------------+ get_material +---------------+
| Learning Tool | --------------> | MCP host |
| server | | (the model) |
| | <-------------- | |
| JSON files | save_flashcards / save_quiz
| on your disk |
| | <-------------- your answers via submit_response
| SM-2 replay | --------------> get_due_items / get_session_state
+----------------+Generation is grounded by instruction: get_material tells the host to build
items from that document's material only.
Related MCP server: pdf-card-mcp
Tools
Tool | What it does |
| Parse a PDF and store its text as study material |
| Return the stored material (the only source for generation) |
| List stored documents with ids, titles, and counts |
| Return the saved flashcards and quiz questions |
| Return what is due now, most overdue first (renders the widget) |
| Store host-generated flashcards |
| Store host-generated quiz questions |
| Grade and record one answer, return updated progress |
| Return mastered / to_review / in_progress / remaining / total, plus a confidence breakdown |
| Write a document's items to an Anki-importable CSV file |
| Destructive: delete a document and everything stored against it |
| Destructive: erase answer history, keep the items |
Setup
Requires Python 3.10 or newer.
pip install learning-tool-mcpFrom a checkout:
pip install -e ".[dev]"Register the server with your MCP client (Claude Desktop, Kiro, and others use this shape):
{
"mcpServers": {
"learning-tool": {
"command": "learning-tool-mcp",
"env": {
"LEARNING_TOOL_DATA_DIR": "~/.learning-tool"
}
}
}
}LEARNING_TOOL_DATA_DIR is the one setting there is; leave it out and the
server stores everything under ~/.learning-tool. The directory is created on
first write.
Example session
You: Ingest
~/papers/photosynthesis.pdfand make me 5 flashcards.The host calls
ingest_material, thenget_materialto read the stored chunks, writes 5 cards from that material, and callssave_flashcards.You: Quiz me.
The host calls
get_due_items, asks you the first question, and callssubmit_responsewith your answer. Quiz answers are graded automatically; flashcards are self-reported ascorrectorincorrect, optionally with a confidence ofguessed,unsure, orconfident.You: How am I doing?
get_session_statereports how many items are mastered, in progress, to review, and untouched. An item counts as mastered after 2 correct answers. It also breaks your answered items down by the confidence you last reported on each, so you can see how much of your progress you were sure about.You: Export these to Anki.
export_documentwrites an Anki-importable CSV next to your data and tells you the path. Import it in Anki with File → Import.
Scheduling is never stored: every schedule is replayed from your answer history, so what you see always matches what you actually answered.
Study widget
In hosts that support the MCP Apps extension, calling get_due_items also
renders an interactive study widget: flip cards, answer multiple-choice and
short-answer questions, report confidence, and watch progress update as you go.
The widget is a single self-contained HTML file shipped inside the package. It
talks to the host over postMessage and calls only submit_response and
get_due_items — the destructive tools are deliberately out of its reach.
Hosts without the extension ignore the widget and work exactly as before.
Development
pytest # the full suite, no network needed
ruff check . && ruff format --check .
mypy --strict src/learning_tool # the package
mypy # tests and toolsCI runs all of the above on Python 3.10 through 3.14 for every push and pull request, so a green local run means a green remote one.
Changes to the study widget need more than the suite, which can only assert
against the widget's source text. tools/ holds the verification tools —
a stdio driver, a wire tracer, and a browser host stub; see tools/README.md.
Specifications live in rebuild/ (the complete, code-free specification of
this application) and specs/open/ (designed but unbuilt features).
Available Tools
12 toolsdelete_documentA
DESTRUCTIVE and irreversible: permanently deletes a document along with its material, flashcards, quiz questions and all answer history. Confirm with the user by name (state the document's title) before calling this tool.
Inputs: document_id (required). Returns: object
export_documentA
Export a document's flashcards and quiz questions to an Anki-importable CSV file on this machine. Writes the file and returns its path; it does not return the CSV text. Defaults to <data_dir>/exports/document--anki.csv, or pass output_path to choose the location. Set include_quiz false to export only flashcards.
Inputs: document_id (required), output_path, include_quiz. Returns: object
get_due_itemsA
Return the study items due for review now, most overdue first, scheduled with the SM-2 spaced-repetition algorithm. Never-reviewed items are included after the overdue ones. Use this to pick what to study next. In hosts that support MCP Apps, calling this renders the interactive study widget.
Inputs: document_id (required). Returns: object
get_materialA
Return the stored source material (text concepts) of a document. Use this material as the ONLY source when generating flashcards and quiz questions: every item must come from this document's material, never from outside facts or your own knowledge.
Inputs: document_id (required). Returns: object
get_session_stateA
Return study progress for a document: mastered, to_review, in_progress, remaining and total item counts, plus a confidence breakdown counting each answered item's latest self-reported confidence (guessed, unsure, confident, unreported).
Inputs: document_id (required). Returns: object
get_study_itemsA
Return the flashcards and quiz questions already saved for a document. This returns generated study items; get_material returns the raw source concepts instead.
Inputs: document_id (required). Returns: object
ingest_materialA
Ingest a PDF and store its text as study material. Returns document_id, title and concept_count. Call get_material next to read the stored material before generating any flashcards or quiz questions.
Inputs: pdf_path (required), title. Returns: object
list_documentsA
List every stored document with its id, title, concept count, flashcard count and quiz count. Call this at the start of a session to discover document ids.
Inputs: no named parameters. Returns: result
reset_progressA
DESTRUCTIVE and irreversible: erases a document's entire answer history, discarding mastery progress and review schedules. Flashcards and quiz questions are kept. Confirm with the user before calling this tool.
Inputs: document_id (required). Returns: object
save_flashcardsB
Save generated flashcards to a document. Each card must have a front and a back. Returns the stored cards with their assigned ids.
Inputs: cards (required), document_id (required). Returns: result
save_quizA
Save generated quiz questions to a document. Each question needs question, answer and question_type (multiple_choice or short_answer). A multiple_choice question also needs options: at least 2, with the answer exactly one of them. Returns the stored questions with their assigned ids.
Inputs: questions (required), document_id (required). Returns: result
submit_responseA
Record an answer to a study item. Quiz questions are graded automatically against the stored answer; flashcards are self-reported, so answer must be 'correct' or 'incorrect'. item_type is 'flashcard' or 'quiz'. Optional confidence is 'guessed', 'unsure' or 'confident'. Returns is_correct and the updated progress.
Inputs: answer (required), item_id (required), item_type (required), document_id (required), +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct resource or lifecycle stage: ingestion vs retrieval, saving flashcards vs quizzes, review scheduling vs progress reporting. The few pairs that could overlap (get_study_items/get_material, get_due_items/get_session_state) are explicitly differentiated in their descriptions.
All tools use a consistent imperative verb + noun snake_case pattern (save_, get_, ingest_, list_, submit_, export_, delete_, reset_). The style is uniform, making the action and target predictable across the entire set.
12 tools is well within the ideal range and each serves a distinct function in the study workflow: ingest, generate/save, retrieve, review, track, export, and manage documents. No tool feels redundant or ornamental.
The core learning loop is covered end-to-end: ingest material, save generated items, retrieve due items, log responses, and monitor progress. Minor gaps exist—there is no way to edit or delete individual flashcards/quiz questions without deleting the whole document—but these are workable and don't block the main workflow.
Maintenance
Related MCP Connectors
Spaced-repetition flashcards your AI writes, quizzes you on by voice, and schedules with FSRS.
Voice-led, FSRS-scheduled flashcards from YouTube, PDFs, web, or text. Auto-graded quizzes.
Build study flashcards and exam-prep decks from your AI chat, all stored locally.
Files what you learn into a personal wiki and quizzes you before you forget it.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceTurns any source material into a guided learning experience with learning maps, notes, four-phase study loop, spaced repetition flashcards, and grounded Q\&A.3MIT
- AlicenseAqualityCmaintenanceConverts dense PDFs into soft, minimal, card-based HTML readers with preserved source text, rendered pages, and cropped tables/figures as images, all processed locally.320 PyPI2MIT
- AlicenseAqualityDmaintenanceEnables browsing and preparing study materials from local documents (PDF, Markdown, text, Word) via tools for overview, search, reading, chunking, and quiz generation.9MIT
- AlicenseNot gradedqualityDmaintenanceConverts study materials like PDFs, slides, and DOCX into a searchable vector database with semantic search, summarization, and flashcard generation, integrated with Notion.5MIT