[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/jasperket-clanki-badge.png)](https://mseep.ai/app/jasperket-clanki)

# Anki MCP - Enhanced Anki Integration for Claude

An enhanced MCP server that enables AI assistants like Claude to interact with Anki flashcard decks through the Model Context Protocol (MCP).

**Based on:** [jasperket/clanki](https://github.com/jasperket/clanki)

## Features

### Core Features (from original clanki)
- Create and manage Anki decks
- Create basic flashcards with front/back content
- Create cloze deletion cards
- Update existing cards and cloze deletions
- Add and manage tags
- View deck contents and card information
- Full integration with AnkiConnect

### Enhancements Added
- **🔍 Card Search Tool**: Search for existing notes using Anki's query language with customizable result limits
- **🧪 Unit Testing**: Comprehensive test suite using Vitest for reliability
- **🏗️ Modular Architecture**: Refactored code with extracted utility functions (`ankiUtils.ts`) for better maintainability
- **🐛 Bug Fixes**: Fixed deck name handling to properly support special characters and spaces

## Prerequisites

- [Anki](https://apps.ankiweb.net/) installed and running
- [AnkiConnect](https://ankiweb.net/shared/info/2055492159) plugin installed in Anki
- Node.js 16 or higher

## Installation

1. Clone this repository:

```bash
git clone https://github.com/liuyixin-louis/anki-mcp.git
cd anki-mcp
```

2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

## Setup

1. Make sure Anki is running and the AnkiConnect plugin is installed and enabled

2. Configure Claude for Desktop to use the server by editing `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "clanki": {
      "command": "node",
      "args": ["/absolute/path/to/clanki/build/index.js"]
    }
  }
}
```

Replace `/absolute/path/to/clanki` with the actual path to your clanki installation.

## Available Tools

### create-deck

Creates a new Anki deck

- Parameters:
  - `name`: Name for the new deck

### create-card

Creates a new basic flashcard in a specified deck

- Parameters:
  - `deckName`: Name of the deck to add the card to
  - `front`: Front side content of the card
  - `back`: Back side content of the card
  - `tags`: (Optional) Array of tags for the card

### create-cloze-card

Creates a new cloze deletion card in a specified deck

- Parameters:
  - `deckName`: Name of the deck to add the card to
  - `text`: Text containing cloze deletions using {{c1::text}} syntax
  - `backExtra`: (Optional) Extra information to show on the back of the card
  - `tags`: (Optional) Array of tags for the card

### update-card

Updates an existing basic flashcard

- Parameters:
  - `noteId`: ID of the note to update
  - `front`: (Optional) New front side content
  - `back`: (Optional) New back side content
  - `tags`: (Optional) New tags for the card

### update-cloze-card

Updates an existing cloze deletion card

- Parameters:
  - `noteId`: ID of the note to update
  - `text`: (Optional) New text with cloze deletions
  - `backExtra`: (Optional) New extra information for the back
  - `tags`: (Optional) New tags for the card

### search-cards ⭐ NEW

Search for existing notes using Anki's query language

- Parameters:
  - `query`: Anki search query (e.g., `deck:MyDeck tag:biology`, `is:due`, `tag:important`)
  - `limit`: (Optional) Maximum number of notes to return (defaults to all matches, capped at 100)

**Example queries:**
- `deck:MyDeck tag:biology` - Find all biology cards in MyDeck
- `is:due` - Find all cards due for review
- `added:7` - Find cards added in the last 7 days
- `tag:important rated:1` - Find important cards rated 1 star

## Development

To modify or extend the server:

1. Make changes to `src/index.ts` or `src/ankiUtils.ts`
2. Run tests with `npm test` to ensure everything works
3. Rebuild with `npm run build`
4. Debug with `npx @modelcontextprotocol/inspector node build/index.js`

### Running Tests

This project includes a comprehensive test suite using Vitest:

```bash
# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run tests with coverage
npm test -- --coverage
```

## What's Different from Original Clanki?

This fork adds several enhancements over [jasperket/clanki](https://github.com/jasperket/clanki):

1. **Card Search**: New `search-cards` tool allows you to find existing cards using Anki's powerful query syntax
2. **Better Code Organization**: Utility functions extracted to `ankiUtils.ts` module with proper TypeScript types
3. **Test Coverage**: Unit tests ensure code reliability and make future changes safer
4. **Bug Fixes**: Deck names with spaces and special characters now work correctly
5. **Developer Experience**: Testing infrastructure makes it easier to contribute and extend

## License

ISC

## Credits

- Original project: [jasperket/clanki](https://github.com/jasperket/clanki)
- Enhanced by: [liuyixin-louis](https://github.com/liuyixin-louis)