# anki-mcp

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that enables LLMs to interact with your Anki flashcard collection. Read decks, search notes, view card contents, and update fields directly from your LLM tool of choice.

## Features

- **Deck Management**: List all available Anki decks
- **Note Search**: Search notes using Anki's powerful search syntax
- **Note Viewing**: View note contents and field values
- **Note Editing**: Update note fields programmatically

## Setup

### Prerequisites

1. **Anki** - Desktop application must be installed and running
2. **AnkiConnect** - Add-on for API access (code: `2055492159`)
3. **Bun** 1.2.16 or later

### Installation

```bash
# Install AnkiConnect in Anki
# Go to Tools → Add-ons → Get Add-ons... → Enter: 2055492159

# Clone and setup this project
git clone git@github.com:mybuddymichael/anki-mcp.git
cd anki-mcp
bun install
```

## Usage

### With Claude Desktop

Add to your [Claude Desktop configuration file](https://modelcontextprotocol.info/docs/quickstart/user/):

```json
{
  "mcpServers": {
    "anki": {
      "command": "bun",
      "args": ["run", "/path/to/anki-mcp/index.ts"]
    }
  }
}
```

### With Other MCP Clients

This server works with any MCP-compatible client. Look up the respective documentation for how to configure it.

## Available tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `get-decks` | Lists all available Anki decks | None |
| `search-notes` | Search notes using Anki syntax | `query` (string) |
| `get-note-fields` | Get note field contents | `noteIds` (number[]) |
| `get-model-names` | List note types/models | None |
| `get-model-field-names` | Get field names for a model | `modelName` (string) |
| `update-note-fields` | Update note field contents | `noteId` (number), `fields` (object) |
| `add-notes` | Add new notes to decks | `notes` (array) |
| `list-media-files` | List all media files | None |
| `check-media-exists` | Check if media file exists | `filename` (string) |
| `store-media` | Store media file to Anki media collection | `filePath` (string) |


## Usage examples

### Adding new cards

> "Add a card with 'bonjour' on the front and 'hello' on the back to my French deck"

> "Create a flashcard for the Spanish word 'biblioteca' meaning 'library' with the tag 'places'"

> "Add these vocabulary words to my German deck: Haus (house), Auto (car), Buch (book)"

### Finding cards

> "Search for all cards in my Biology deck, then show me their contents"
> 
> First: Search returns note IDs → Second: Get field contents for those IDs

> "Find my Spanish vocabulary cards tagged with 'food', then show me what they contain"

### Updating cards

> "Update the back of card #1234567890 to include pronunciation: 'biblioteca [bee-blee-oh-TEH-kah]'"

> "Fix the typo on the front of that card - change 'recieve' to 'receive'"

### Deck info

> "What decks do I have available?"

> "What note types exist in my Anki collection?"

> "Show me the field names for my Cloze note type"



## Related Links

- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [AnkiConnect Documentation](https://github.com/FooSoft/anki-connect)
- [Anki Manual](https://docs.ankiweb.net/)

## License

MIT