flashcard-jp-mcp 0.1.0

MCP server bridging Claude (Desktop / Code / .ai) to a flashcard-jp deployment.

flashcard-jp-mcp

MCP server that lets Claude (Desktop, Code, or .ai web via Connectors) add words to a flashcard-jp deployment. Once installed, you can chat with Claude like:

"Aggiungi al mio Test Mazzo: kau (acquistare), matsu (aspettare), asobu (giocare). Genera anche le frasi mnemoniche italiane."

Claude calls add_cards_bulk once and the words land in the deck.

Install

# Recommended: ephemeral install per Claude session
uvx flashcard-jp-mcp

# Or install once into the user environment
pipx install flashcard-jp-mcp

Get an API token

1. Open the flashcard-jp web app online.
2. Click 🔑 in the top navbar → Crea token.
3. Give it a name (e.g. claude-desktop) → copy the fjp_… value once.
4. Paste it into the MCP server's environment (see below). The web UI keeps only a SHA-256 hash — losing the raw value means you have to create a new token.

Configure Claude Desktop

Add to ~/.claude/settings.json (or use claude mcp add flashcard-jp in Claude Code):

{
  "mcpServers": {
    "flashcard-jp": {
      "command": "uvx",
      "args": ["flashcard-jp-mcp"],
      "env": {
        "FLASHCARD_API_BASE": "https://flashcard-jp-production.up.railway.app",
        "FLASHCARD_API_TOKEN": "fjp_PASTE_YOUR_TOKEN_HERE"
      }
    }
  }
}

Restart Claude. The tools below become available in the chat.

Tools

Tool	What it does
whoami	Returns the authenticated user's email + last-studied deck id. Quick auth check.
list_decks	Every deck visible to the user, with progress (cards_total, cards_done, cards_left, cards_available_today, completed).
get_deck(deck_id)	A deck's full word list — useful so Claude can dedupe before adding.
create_deck(name)	Create a private deck owned by the user.
add_card_to_deck(deck_id, romajii, kana, italiano, mnemonic?, emoji?)	One word → Word + 2 Cards (forward + reverse).
add_cards_bulk(deck_id, cards)	Several entries in one call, returns {added: [...], skipped: [...]}.

Romajii must be Hepburn, lowercase, ASCII (ohayoo, not ohayō). Kana should be the hiragana / katakana reading only — no kanji.

Environment variables

Var	Default	Required
FLASHCARD_API_BASE	https://flashcard-jp-production.up.railway.app	no
FLASHCARD_API_TOKEN	—	yes

Limits

• Starting decks (is_starting=True) are read-only. Trying to mutate one returns 403; the tool surfaces that as an error message Claude can show in the chat.
• Token leaks: each token grants full deck-write access for the user it belongs to. Revoke from the web UI's 🔑 menu if exposed.

License

MIT.