@studycards/mcp

StudyCards MCP server

A Model Context Protocol server that lets Claude (Desktop or Code) manage your StudyCards flashcards in natural language. It is a thin wrapper around the StudyCards REST v1 API — it talks only to the public HTTP API, never to the database directly.

This is a standalone package (@studycards/mcp). The MCP SDK lives here, not in the main app's dependencies.

Prerequisites

• Node.js 18+ (uses the built-in global fetch).
• A StudyCards API key:
  • Sign in to StudyCards.
  • Go to Settings → API Keys.
  • Click Create, name the key, and copy the sk_live_… value (shown once).

Install

No manual install needed — the configs below run the server via npx, which fetches and caches the published package automatically.

To run it from source instead (development, or before the package is published), clone this repo and replace the npx -y @studycards/mcp@latest command shown below with node /absolute/path/to/mcp/index.mjs. Smoke test (no key / network needed) prints usage and the tool list:

node index.mjs --help

Configuration

The server reads two environment variables:

Variable	Required	Default
STUDYCARDS_API_KEY	yes	—
STUDYCARDS_API_URL	no	https://studycards.io/api/v1

Claude Code

Fastest — one command (no file editing):

claude mcp add studycards --env STUDYCARDS_API_KEY=sk_live_xxxx -- npx -y @studycards/mcp@latest

Or add to a .mcp.json in your project (or your user config):

{
  "mcpServers": {
    "studycards": {
      "command": "npx",
      "args": ["-y", "@studycards/mcp@latest"],
      "env": {
        "STUDYCARDS_API_KEY": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "studycards": {
      "command": "npx",
      "args": ["-y", "@studycards/mcp@latest"],
      "env": {
        "STUDYCARDS_API_KEY": "sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop after editing.

The fastest in-app path is Connect AI inside StudyCards: it creates a key, shows these snippets pre-filled, and tests the connection.

Tools

Tool	REST mapping	Description
list_decks	GET /sets	List all decks with card counts.
get_deck	GET /sets/{id} (+ cards)	Get one deck; optionally include its cards.
create_deck	POST /sets	Create a deck (name, optional description).
update_deck	PATCH /sets/{id}	Update a deck's name and/or description.
delete_deck	DELETE /sets/{id}	Delete a deck and its cards.
list_cards	GET /sets/{id}/cards	List a deck's cards (1-based index, front/back text).
add_cards	POST /sets/{id}/cards	Add 1–50 cards ({front, back} each).
edit_card	PATCH /cards/{id}	Edit a card's front and/or back (kind & image kept).
delete_card	DELETE /cards/{id}	Delete a single card.
get_due_cards	GET /sets/{id}/due-cards	Cards due for review now (overdue + new).
record_review	POST /cards/{id}/review	Record a review (correct/false) → SM-2 schedule.

Each tool returns the REST JSON as readable text. On an API error it returns an error message (e.g. HTTP 403 … plan limit reached) instead of crashing.

Example prompts

• "List my StudyCards decks."
• "Create a deck called Spanish Verbs and add 10 cards covering the most common irregular verbs (front = infinitive, back = English + conjugation)."
• "In my Biology deck, add cards for mitosis, meiosis and cytokinesis."
• "Show the cards in the deck with id … and fix the typo on the mitosis card."
• "Rename my Bio 101 deck to Cell Biology and delete the empty card."

Notes

• Card create/edit uses the API's simplified text model (v3): editing rewrites a side's text while preserving its kind and any image. For full layouts use the web app. See ../docs/api.md.
• Limits (deck/card counts) are enforced by the API and surface as HTTP 403 errors through the tools.