srs-mcp
This server provides a headless spaced-repetition flashcard system via MCP, letting agents create, review, and manage cards with FSRS scheduling.
Author cards:
add_card(front, back)creates a new flashcard and schedules it (due immediately).List due cards:
due_cards()returns cards due now, optionally filtered by deck or limited count, for quizzing.Record recall:
grade_card(card_id, rating)grades a review (again/hard/good/easy) and updates the FSRS schedule.Edit card content:
edit_card()changes front/back/deck without altering the existing schedule.Suspend/unsuspend cards: Temporarily shelve or restore cards without losing history.
List all cards:
list_cards()gives an overview regardless of due date, including reps and suspension status.Delete cards:
delete_card()permanently removes a card.Get statistics:
stats()shows total cards, due now, reviews, and deck breakdowns.
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., "@srs-mcp show me my due cards"
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.
srs-mcp
Agent-agnostic MCP server for spaced-repetition learning — no Anki GUI, no Xvfb, no AnkiConnect. Bring your own agent; this brings the card box + the scheduler.
It wraps FSRS (the Free Spaced Repetition Scheduler, the same algorithm modern Anki uses) around a tiny SQLite store, so an agent can author cards, see what's due, and record recall — entirely headless.
Why not headless Anki?
Driving the Anki desktop app headless means Qt + a virtual framebuffer
(Xvfb) + the AnkiConnect add-on — brittle and version-coupled. The
anki PyPI package can drive a real .anki2 collection GUI-less if you
need interop with your phone's Anki. But if you just want spaced
repetition behind an API, you don't need Anki at all: FSRS is a library,
and this server is ~200 lines around it.
Related MCP server: srs-mcp
Tools
add_card(front, back) -> {card_id, due}— author + schedule a card. Keepbackshort — a word or a phrase; a card you can't grade in seconds is a note, not a flashcarddue_cards(q=None, limit=20) -> [{card_id, front, back, deck, due}]— what's due now, optionally narrowed to a topic (q="horace")grade_card(card_id, rating) -> {card_id, rating, next_due, reps}— record recall (again/hard/good/easy, or 1-4)edit_card(card_id, front=None, back=None)— edit content in place; schedule is preserved (fix typos / shorten a long answer instead of duplicating)suspend_card(card_id)/unsuspend_card(card_id)— shelve a card (kept with its history, removed from the due queue) / restore itlist_cards(q=None, limit=50)— overview regardless of due datedelete_card(card_id)— remove one (reset / cleanup)stats(deck=None) -> {total, due_now, suspended, reviews, decks}
Finding cards: search, not decks
Cards are found by searching their text — due_cards(q="horace") — rather
than by filing them into decks up front. Nothing writes the deck field any
more; put the topic in the card itself ("Horace, Odes 1.11: …") and it stays
findable.
Decks were a single-valued, free-text, exact-match label with no per-deck
scheduling attached, so they bought nothing a search doesn't, and cost
accuracy: on the deck this was measured against, agents had invented ten
names for Horace across five separator conventions, so the best possible
deck="Horace" returned 20 of 97 Horace cards while q="horac" returns 89 —
including ones misfiled under Talks. The column and the deck= filter on
due_cards/list_cards/stats remain for cards labelled by older versions.
See plans/002-decks.md.
The review loop: due_cards → quiz the user with front → check against
back → grade_card. FSRS computes the next due date from the rating.
Run
uv sync
# HTTP (default; for Railway / remote agents)
PORT=8000 uv run srs-mcp
# or stdio (local agent)
MCP_TRANSPORT=stdio uv run srs-mcpStorage
Two backends, chosen at startup:
Postgres (shared deck) — set
SRS_DATABASE_URL(orDATABASE_URL) to a Postgres connection string (e.g. a Neon DB). Every deployment that points at the same URL reads/writes one shared deck, so you can add and review cards from anywhere (local, Railway, etc.). FSRS card ids are large, so thecards.card_idcolumn isBIGINTon Postgres. Requires thepsycopgdependency (already declared).SQLite (fallback) — when no
*DATABASE_URLis set, cards live in a SQLite file atSRS_DB(default./srs.db). Single-host / offline. In a SQLite-on-Railway setup, mount a volume at/dataand keepSRS_DB=/data/srs.dbso the box survives redeploys.
The schema is identical (table cards) and auto-created on first use.
Available Tools
9 toolsadd_cardA
Author a new flashcard and schedule it. front is the prompt/question,
back is the answer. Optional deck groups cards (default 'default').
Returns JSON {card_id, due}. The card is due immediately (first review).
Inputs: back (required), front (required), deck. Returns: result
delete_cardC
Delete a card by id (reset / cleanup).
Inputs: card_id (required). Returns: result
due_cardsA
List cards due for review now (due <= now), soonest first. Optionally
filter by deck. Returns a JSON array of {card_id, front, back, deck, due}.
Quiz the user with front, check against back, then call grade_card.
Returns '[]' when nothing is due.
Inputs: deck, limit. Returns: result
edit_cardA
Edit a card's content without disturbing its schedule. Update any of
front, back, deck (omit or pass null to leave unchanged); the FSRS
review state (difficulty, stability, due date, reps) is preserved. Use
this to fix typos or add context instead of creating a duplicate card.
Returns JSON {card_id, front, back, deck}.
Inputs: card_id (required), back, deck, front. Returns: result
grade_cardA
Record a review of a card. rating is how well it was recalled:
'again' (forgot), 'hard', 'good', or 'easy' (1-4 also accepted). FSRS
updates the schedule; returns JSON {card_id, rating, next_due, reps}.
Inputs: rating (required), card_id (required). Returns: result
list_cardsA
List cards (newest first) regardless of due date, for an overview.
Optionally filter by deck. Returns JSON array of
{card_id, front, back, deck, due, reps, suspended}.
Inputs: deck, limit. Returns: result
statsA
Summary of the card box: total cards, how many are due now, total
reviews, and the deck list. Optionally scope counts to one deck.
Inputs: deck. Returns: result
suspend_cardA
Shelve a card: keep it (with its full history and schedule) but remove it from the due queue, so it won't surface in due_cards until unsuspended. Reversible, non-destructive alternative to delete_card for cards you're unsure about. Returns JSON {card_id, suspended}.
Inputs: card_id (required). Returns: result
unsuspend_cardA
Un-shelve a previously suspended card, returning it to the review queue (it becomes due again per its existing schedule). Returns JSON {card_id, suspended}.
Inputs: card_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose: adding, deleting, editing, listing, reviewing, grading, stats, suspending, and unsuspending cards. No two tools overlap in functionality.
All tool names follow a consistent verb_noun pattern in snake_case, e.g., add_card, delete_card, grade_card. Names are predictable and readable.
9 tools is well-scoped for a spaced repetition system, covering all essential operations without bloat. Each tool earns its place.
Covers core CRUD, review workflow, statistics, and suspension. Missing explicit deck management (e.g., create/delete deck) but decks are manageable via card properties.
Maintenance
Related MCP Connectors
Build and study spaced-repetition flashcards with your agent.
Spaced-repetition flashcards in Markdown: create cards, manage decks and study with FSRS.
Spaced-repetition flashcards your AI writes, quizzes you on by voice, and schedules with FSRS.
Agent-native spaced-recall system of record. Deterministic dueAt via remote MCP for Muse/any agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to store, search, and manage persistent memories, todos, kanban boards, reminders, and progress trackers in a local SQLite database.1Apache 2.0
- AlicenseAqualityDmaintenanceProvides spaced-repetition scheduling with the SM-2 algorithm as MCP tools, enabling agents to manage review items like flashcards or vocab locally. It supports adding, grading, and listing due items, plus optional pro features for export and forecast.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to create spaced-repetition flashcards from material being learned, quiz users aloud, grade answers, and schedule reviews using the FSRS algorithm through a self-hosted MCP server.8AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables an AI assistant to create, search, and manage locally stored spaced-repetition flashcards, quiz users in chat with front-only prompts, and grade their answers using SM-2 scheduling.MIT