Skip to main content
Glama

flashlearn-mcp

An MCP (Model Context Protocol) server for the FlashLearnAI public API. Add it to Claude Code, Claude Desktop, or any MCP client and say "make me a flashcard deck about X and quiz me on it": the model can generate decks with AI, browse sets, run SM-2 spaced-repetition study sessions, and read API usage, all through your own FlashLearnAI API key.

Built with the official TypeScript SDK v2 (@modelcontextprotocol/server, 2026-07-28 MCP spec). stdio transport. MIT licensed.

Quickstart (under 5 minutes)

Requirements: Node.js 20 or later and a FlashLearnAI API key. Mint a key at flashlearnai.witus.online/developer/keys (sign in, Developer Portal, API Keys, Create key).

git clone https://github.com/dapperAuteur/flashlearn-mcp.git
cd flashlearn-mcp
pnpm install
pnpm build

Claude Code

claude mcp add flashlearn -e FLASHLEARN_API_KEY=fl_pub_your_key_here -- node /absolute/path/to/flashlearn-mcp/dist/index.js

Then in a Claude Code session: "use the flashlearn tools to generate a deck about photosynthesis and quiz me."

Claude Desktop

Add to claude_desktop_config.json (Settings, Developer, Edit Config):

{
  "mcpServers": {
    "flashlearn": {
      "command": "node",
      "args": ["/absolute/path/to/flashlearn-mcp/dist/index.js"],
      "env": {
        "FLASHLEARN_API_KEY": "fl_pub_your_key_here"
      }
    }
  }
}

Restart Claude Desktop and the flashlearn tools appear in the tools menu.

After npm publish

Once the package is published to npm, the local path form above can be replaced with npx:

claude mcp add flashlearn -e FLASHLEARN_API_KEY=fl_pub_your_key_here -- npx -y flashlearn-mcp
{
  "mcpServers": {
    "flashlearn": {
      "command": "npx",
      "args": ["-y", "flashlearn-mcp"],
      "env": { "FLASHLEARN_API_KEY": "fl_pub_your_key_here" }
    }
  }
}

Verify without a host

The MCP Inspector exercises the server directly:

FLASHLEARN_API_KEY=fl_pub_your_key_here npx @modelcontextprotocol/inspector node dist/index.js

Connect, open the Tools tab, and run ping. It reports the configured API base and whether a key is set, without calling the API.

Related MCP server: TalkToAnki

Configuration

Env var

Required

Default

Purpose

FLASHLEARN_API_KEY

yes

none

API key from the developer dashboard. Sent as Authorization: Bearer. Never logged, never echoed in tool output (a test suite asserts this).

FLASHLEARN_API_BASE

no

https://flashlearnai.witus.online

API base URL. The default is the production URL from the FlashLearnAI OpenAPI spec; override it for a local or staging instance.

The server starts without a key (so hosts can list tools), but every API-backed tool returns an error naming the fix until the key is set.

Tools

Tool

API route

What it does

ping

none

Liveness plus configuration (API base, key set or not).

list_sets

GET /api/v1/sets

List the key's flashcard sets, paginated.

get_set

GET /api/v1/sets/{id}

One set with all cards (owned or public).

generate_cards

POST /api/v1/generate

AI-generate a deck for a topic; reuses an existing public deck for the same topic when one exists.

create_study_session

POST /api/v1/study/sessions

Start a study session; returns shuffled cards.

submit_review

POST /api/v1/study/sessions/{id}/complete

Submit per-card results; updates SM-2 scheduling and returns accuracy stats.

get_usage

GET /api/v1/usage

Billing-period usage and limits for the key.

Resources: flashlearn://getting-started (how the tools fit together) and flashlearn://openapi (the live OpenAPI 3.1 spec of the underlying API).

What the tools return and why (output trimming)

Tool output goes into a model's context window, so every response is trimmed to what the model needs:

  • Cards are reduced to id, front, back. Media URLs, alt text, video fields, multiple-choice options, and answer-key fields are dropped. A raw get_set card can carry 14 fields; the trimmed card carries 3.

  • Set descriptions are capped at 160 characters in listings.

  • list_sets drops rating and createdAt; they do not help a model pick a deck.

  • generate_cards, submit_review, and get_usage pass through shapes that are already compact.

Every tool also declares a zod outputSchema and returns structuredContent, so clients get machine-readable results next to the text block.

Error handling

  • API errors become MCP tool errors (isError: true) with the fix in the message: a 401 points at the key dashboard, a quota 429 points at get_usage, a 404 suggests list_sets. Never a silent empty result.

  • Burst rate limits (RATE_LIMIT_EXCEEDED) are retried once with a capped backoff. Monthly quota exhaustion (QUOTA_EXCEEDED, same HTTP 429, different code) is never retried, because a retry cannot succeed inside the billing period.

  • The API key never appears in logs, errors, or output. The client never interpolates it, and a redaction pass scrubs it from any upstream message as a second fence. test/redaction.test.ts proves this for happy, 401, 429, network-failure, and hostile-echo paths.

Spec vs code notes (upstream API)

This server is coded against the FlashLearnAI OpenAPI spec plus the actual route code. Two places disagree; the server follows the code:

  1. The spec's UsageResponse schema shows the usage object as the whole 200 body; the route wraps it in the standard { data, meta } envelope like every other endpoint.

  2. The spec documents POST /api/v1/generate as returning 201; the route returns 200 (with source: "shared") when it serves an existing public deck instead of generating.

Both are noted for the flashlearn-ai repo's spec-is-contract cleanup workstream.

Development

pnpm install
pnpm typecheck   # tsc strict, no emit
pnpm lint        # eslint flat config, type-checked rules
pnpm test        # vitest: 33 tests, mocked API, in-process MCP client
pnpm build       # emits dist/
pnpm demo        # live end-to-end demo against production (needs FLASHLEARN_API_KEY)

Tests connect a real MCP client to the real server factory in process (per the SDK v2 testing guide) and mock the FlashLearnAI API at the fetch boundary, so tool behavior, schema validation, error mapping, and redaction are all covered without network access.

Activate the commit guard once per clone:

git config core.hooksPath .githooks

Roadmap

  • v1 (this): stdio transport, API-key auth, read/generate/study tools.

  • v2: Streamable HTTP transport for a hosted remote server, and OAuth if the product's developer surface grows it. Not started; stdio is the only transport today.

License

MIT. See LICENSE.

flashlearn-mcp

Available Tools

7 tools
create_study_sessionStart a study sessionA

Start a spaced-repetition study session for a set. Returns a sessionId and the shuffled cards to quiz the user with. Finish with submit_review to record results and update SM-2 scheduling.

Inputs: setId (required), studyMode, studyDirection. Returns: setId, setName, sessionId, studyMode, +3 more

generate_cardsGenerate flashcards with AIA

Generate a flashcard deck about a topic using FlashLearnAI. If a public deck for the topic already exists it is reused (source: "shared") and no generation quota is spent; otherwise a new deck is created (source: "generated"). Counts against the monthly generation quota when it generates.

Inputs: topic (required), title, description. Returns: setId, source, cardCount, flashcards

get_setGet a flashcard setA
Read-only

Fetch one flashcard set with all of its cards (front and back text). Works for sets owned by the key and for public sets.

Inputs: setId (required). Returns: id, title, isPublic, cardCount, +2 more

get_usageGet API usageA
Read-only

Show the current billing-period usage and limits for the configured API key: API calls, AI generation calls, overage calls, and the tier limits.

Inputs: no named parameters. Returns: usage, limits, period, apiTier, +1 more

list_setsList flashcard setsA
Read-only

List the flashcard sets owned by the configured API key, newest first. Returns id, title, a short description, and card count per set, plus pagination.

Inputs: page, limit, source. Returns: sets, pagination

pingPingA
Read-onlyIdempotent

Check that the FlashLearn MCP server is alive and see how it is configured (API base URL and whether an API key is set). Makes no API call.

Inputs: no named parameters. Returns: ok, server, apiBase, version, +1 more

submit_reviewSubmit study session resultsA
Idempotent

Complete a study session by submitting one result per reviewed card. Updates the SM-2 spaced-repetition schedule and returns accuracy and duration stats.

Inputs: results (required), sessionId (required). Returns: status, accuracy, sessionId, totalCards, +4 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: health check, listing sets, retrieving a set, usage info, generating cards, creating a study session, and submitting reviews. There is no functional overlap between any tools.

    Naming Consistency5/5

    All tool names follow a clear verb_noun snake_case pattern (list_sets, get_set, get_usage, generate_cards, create_study_session, submit_review). Even 'ping' fits the imperative verb style, so the naming is fully consistent.

    Tool Count5/5

    Seven tools is well-scoped for a flashcard MCP server. Each tool covers a necessary part of the workflow: discovery, content generation, retrieval, usage monitoring, and study session management, without bloat or missing essentials.

    Completeness4/5

    The core workflows are covered: listing, retrieving, generating, and studying sets, plus session creation and completion. The only minor gap is the lack of explicit update/delete operations for flashcard sets, which is a reasonable omission given the server's study-focused purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      An MCP server that enables AI assistants to interact with the Anki flashcard application for studying, deck management, and note creation. It supports natural language interaction for reviewing cards, searching content, and managing media files across local and remote environments.
      981 npm
      556
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to seamlessly manage Anki flashcards, decks, and templates through the AnkiConnect API. It supports intelligent querying, batch note creation, and detailed study progress analysis using natural language.
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local Leitner flashcard MCP server enabling AI clients to create decks, manage cards, study with spaced repetition, and track progress.
      MIT