flashlearn-mcp
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., "@flashlearn-mcp make me a flashcard deck about the French Revolution 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.
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 buildClaude Code
claude mcp add flashlearn -e FLASHLEARN_API_KEY=fl_pub_your_key_here -- node /absolute/path/to/flashlearn-mcp/dist/index.jsThen 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.jsConnect, 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 |
| yes | none | API key from the developer dashboard. Sent as |
| no |
| 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 |
| none | Liveness plus configuration (API base, key set or not). |
|
| List the key's flashcard sets, paginated. |
|
| One set with all cards (owned or public). |
|
| AI-generate a deck for a topic; reuses an existing public deck for the same topic when one exists. |
|
| Start a study session; returns shuffled cards. |
|
| Submit per-card results; updates SM-2 scheduling and returns accuracy stats. |
|
| 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 rawget_setcard can carry 14 fields; the trimmed card carries 3.Set descriptions are capped at 160 characters in listings.
list_setsdropsratingandcreatedAt; they do not help a model pick a deck.generate_cards,submit_review, andget_usagepass 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 atget_usage, a 404 suggestslist_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.tsproves 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:
The spec's
UsageResponseschema shows the usage object as the whole 200 body; the route wraps it in the standard{ data, meta }envelope like every other endpoint.The spec documents
POST /api/v1/generateas returning 201; the route returns 200 (withsource: "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 .githooksRoadmap
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 toolscreate_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 setARead-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 usageARead-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 setsARead-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
pingPingARead-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 resultsAIdempotent
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
Scored across 7 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceAn 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 npm556MIT
- AlicenseNot gradedqualityDmaintenanceAn 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.4MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Mochi Cards API, enabling AI assistants to manage flashcards, decks, and templates.20 npm12MIT
- AlicenseNot gradedqualityDmaintenanceLocal Leitner flashcard MCP server enabling AI clients to create decks, manage cards, study with spaced repetition, and track progress.MIT