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

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 installed and running
AnkiConnect plugin installed in Anki
Node.js 16 or higher

Installation

Clone this repository:

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

Install dependencies:

npm install

Build the project:

npm run build

Setup

Make sure Anki is running and the AnkiConnect plugin is installed and enabled
Configure Claude for Desktop to use the server by editing claude_desktop_config.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:

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

Running Tests

This project includes a comprehensive test suite using Vitest:

# 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:

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

License

ISC

Credits

Original project: jasperket/clanki
Enhanced by: liuyixin-louis