flashcard-jp-mcp 0.3.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 (one command)

Claude Desktop (Mac / Windows / Linux)

uvx --from flashcard-jp-mcp flashcard-jp-mcp-install-desktop

This writes the flashcard-jp entry into the Claude Desktop config at the OS-correct path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop. Done.

Claude Code (CLI)

claude mcp add flashcard-jp -- uvx flashcard-jp-mcp

Restart your Claude Code session.

Manual (any client)

{
  "mcpServers": {
    "flashcard-jp": {
      "command": "uvx",
      "args": ["flashcard-jp-mcp"]
    }
  }
}

The 6 tools below become available in chat.

Prereq: uv installed. If uvx is missing:

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
# Windows PowerShell:
# powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

How auth works

The first tool call asks you for an API token via MCP elicitation — Claude pops up a prompt explaining where to mint it. Paste the fjp_… value, the server saves it to ~/.config/flashcard-jp-mcp/config.json (perm 600), and you're done. Token resolution order:

1. FLASHCARD_API_TOKEN env var (per-deployment override).
2. ~/.config/flashcard-jp-mcp/config.json (set by the elicit prompt or by flashcard-jp-mcp-setup).
3. MCP elicitation prompt (only if your client supports it; Claude Desktop and recent Claude Code do).
4. Friendly error pointing at the setup recipe.

Mint the token (when Claude asks, or up-front)

1. Open https://flashcard-jp-production.up.railway.app and log in with Google.
2. Click 🔑 in the top navbar.
3. Click Crea token, name it (e.g. claude-desktop), copy the fjp_… value (shown once).

Out-of-band setup (terminal, no Claude required)

uvx flashcard-jp-mcp-setup

The CLI prints the URL, reads the token from stdin, validates it against the API, and saves it to the config file. Useful for clients that don't support elicitation, or if you'd rather not expose the token through chat.

Override the API base

If you self-host flashcard-jp on a different URL, set FLASHCARD_API_BASE in the MCP env:

"env": {
  "FLASHCARD_API_BASE": "https://your-flashcard-jp.example.com"
}

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.