Skip to main content
Glama

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. Keep back short — a word or a phrase; a card you can't grade in seconds is a note, not a flashcard

  • due_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 it

  • list_cards(q=None, limit=50) — overview regardless of due date

  • delete_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-mcp

Storage

Two backends, chosen at startup:

  • Postgres (shared deck) — set SRS_DATABASE_URL (or DATABASE_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 the cards.card_id column is BIGINT on Postgres. Requires the psycopg dependency (already declared).

  • SQLite (fallback) — when no *DATABASE_URL is set, cards live in a SQLite file at SRS_DB (default ./srs.db). Single-host / offline. In a SQLite-on-Railway setup, mount a volume at /data and keep SRS_DB=/data/srs.db so the box survives redeploys.

The schema is identical (table cards) and auto-created on first use.

Available Tools

9 tools
add_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

    A4/5.0

    Scored across 9 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: adding, deleting, editing, listing, reviewing, grading, stats, suspending, and unsuspending cards. No two tools overlap in functionality.

    Naming Consistency5/5

    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.

    Tool Count5/5

    9 tools is well-scoped for a spaced repetition system, covering all essential operations without bloat. Each tool earns its place.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to store, search, and manage persistent memories, todos, kanban boards, reminders, and progress trackers in a local SQLite database.
      1
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      8
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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