[](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)
