# flashcards-mcp

A spaced repetition flashcard MCP server for Claude. Uses the FSRS-5 algorithm (successor to Anki's SM-2) with an interactive card UI, text-to-speech, and image support.

## Install

### npx (quickest)

```bash
npx flashcards-mcp
```

Add to `~/.claude/.mcp.json`:

```json
{
  "mcpServers": {
    "flashcards": {
      "command": "npx",
      "args": ["flashcards-mcp"]
    }
  }
}
```

### curl (auto-configures Claude)

```bash
curl -fsSL https://raw.githubusercontent.com/zcsabbagh/flashcards-mcp/main/install.sh | bash
```

### Homebrew

```bash
brew tap zcsabbagh/tap
brew install flashcards-mcp
```

Then add to `~/.claude/.mcp.json`:

```json
{
  "mcpServers": {
    "flashcards": {
      "command": "flashcards-mcp"
    }
  }
}
```

## Usage

After restarting Claude, try:

- **"create a deck called Algorithms"** — creates a new deck
- **"add a card: What is Big O? / A notation for algorithm time complexity"** — adds a card
- **"get due cards"** — opens the interactive flashcard UI
- **"get due cards for deck 1"** — filters to a specific deck

### Keyboard shortcuts (in the flashcard UI)

| Key | Action |
|-----|--------|
| Space / Enter | Flip card |
| 1-4 | Rate (Again, Hard, Good, Easy) |
| Arrow Left/Right | Previous/Next card |
| V | Toggle voiceover (requires ElevenLabs API key) |

### Images

Cards support images on front and back faces:

```
"add a card with front_image from /path/to/image.png"
"set card 5 front image to https://example.com/photo.jpg"
```

### Text-to-Speech

Add your ElevenLabs API key to the MCP config:

```json
{
  "mcpServers": {
    "flashcards": {
      "command": "npx",
      "args": ["flashcards-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "sk_..."
      }
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `create_deck` | Create a new deck |
| `list_decks` | List all decks with stats |
| `add_card` | Add a single card (supports markdown, images) |
| `bulk_add_cards` | Add multiple cards at once |
| `get_due_cards` | Get due cards with interactive UI |
| `review_card` | Submit a rating (1-4) |
| `search_cards` | Search cards by keyword |
| `get_deck_stats` | Mastery distribution, retention rate |
| `get_card_image` | Lazy-load card images |
| `set_card_image` | Add/replace card images |
| `tts` | Text-to-speech via ElevenLabs |
| `delete_card` | Delete a card |
| `delete_deck` | Delete a deck and all its cards |
| `get_review_history` | Card scheduling history |

## How it works

- **FSRS-5 algorithm** schedules reviews based on stability, difficulty, and elapsed time
- **SQLite** stores everything locally at `~/.claude/mcp-servers/flashcards/data/flashcards.db`
- **MCP App UI** renders an interactive flashcard widget directly in Claude's chat
- **Images** stored as base64 in the database, lazy-loaded one at a time
- **Markdown** supported in card content (code blocks, lists, headers, etc.)

## License

MIT