Anki-AI - Anki MCP Server & CLI

npx skills add briansunter/anki-ai

MCP server and CLI for Anki integration via Anki-Connect. 96 tools across 8 categories for creating flashcards, managing reviews, analyzing learning data, and automating Anki workflows.

Install as Claude Skill

npx skills add briansunter/anki-ai

Quick Start

Prerequisites

1. Anki - Desktop application
2. Anki-Connect - Install via Anki > Tools > Add-ons > Get Add-ons > Code: 2055492159

Installing Anki-Connect

Step 1: Install the Add-on

1. Open Anki Desktop
2. Go to Tools → Add-ons → Get Add-ons...
3. Enter code: 2055492159
4. Click OK

Step 2: Configure Permissions (Recommended)

By default, Anki-Connect only allows localhost connections. To use with MCP:

1. Go to Tools → Add-ons → AnkiConnect → Config
2. Replace the config with:

{
  "webBrowserBind": false,
  "webBindAddress": "127.0.0.1",
  "webBindPort": 8765,
  "corsOriginList": ["http://localhost", "app://obsidian.md"]
}

3. Save and restart Anki

Step 3: Verify Connection

Run this command to test:

curl localhost:8765 -d '{"action":"version","version":6}'

You should see: {"result": 6, "error": null}

MCP Configuration

Claude Desktop

Platform	Config File
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["anki-ai"]
    }
  }
}

Restart Claude Desktop after editing.

Claude Code

Create .mcp.json in your project root:

{
  "servers": {
    "anki": {
      "command": "npx",
      "args": ["anki-ai"]
    }
  }
}

CLI

# List all decks
npx anki-ai deck list

# Create a note
npx anki-ai note add --deck Default --model Basic --front "Q" --back "A"

# Search notes
npx anki-ai note find "deck:Default"

# Run any of the 96 tools directly
npx anki-ai run findCards '{"query":"deck:Default is:due","limit":20}'

# List all available tools
npx anki-ai tools

Common Workflows

Quick Card Creation

# Create a vocabulary card
npx anki-ai note add --deck "Japanese::Vocab" --model Basic \
  --front "猫 (neko)" --back "cat" --tags japanese,N5

# Create multiple cards in a deck
npx anki-ai run addNotes '{"notes":[
  {"deckName":"Spanish","modelName":"Basic","fields":{"Front":"Hola","Back":"Hello"},"tags":["spanish"]},
  {"deckName":"Spanish","modelName":"Basic","fields":{"Front":"Adiós","Back":"Goodbye"},"tags":["spanish"]}
]}'

Review Cards

# Get next 10 due cards in review order (Learning > Review > New)
npx anki-ai card next --limit 10

# Get due cards for a specific deck
npx anki-ai card next --deck "Japanese::Vocab" --limit 5

# Answer a card (1=Again, 2=Hard, 3=Good, 4=Easy)
npx anki-ai card answer 123456789 3

Check Progress

# Today's review count
npx anki-ai stats today

# Due cards with breakdown by type
npx anki-ai stats due --deck "Japanese"

# Deck statistics (new/learn/review/total)
npx anki-ai deck stats "Japanese::Vocab"

CLI Commands

deck

Command	Description
deck list	List all deck names
deck create <name>	Create a deck (use :: for nesting)
deck stats <names...>	Get new/learn/review/total counts
deck delete <names...>	Delete decks and their cards

note

Command	Description
note add --deck D --model M --front F --back B [--tags t1,t2]	Create a note
note find <query> [--offset N] [--limit N]	Search notes
note info <ids...>	Get note details
note update <id> [--fields '{}'] [--tags t1,t2]	Update a note
note delete <ids...>	Delete notes permanently
note tags <id>	Get tags for a note

card

Command	Description
card find <query> [--offset N] [--limit N]	Search cards
card info <ids...>	Get card details
card suspend <ids...>	Suspend cards
card unsuspend <ids...>	Unsuspend cards
card answer <cardId> <ease>	Answer card (1=Again 2=Hard 3=Good 4=Easy)
card next [--deck D] [--limit N]	Get next due cards in review order

model

Command	Description
model list	List all note types
model fields <name>	Get field names for a model
model create --name N --fields f1,f2 --templates '<json>'	Create model

stats

Command	Description
stats today	Today's review count
stats due [--deck D]	Due cards with learning/review breakdown
stats collection	Full collection statistics

Generic Runner

Any of the 96 tools can be called directly:

npx anki-ai run <toolName> '<jsonArgs>'
npx anki-ai run addNote '{"deckName":"Default","modelName":"Basic","fields":{"Front":"Hello","Back":"World"}}'
npx anki-ai run deckNames

Tool Categories (96 tools)

Category	Count	Examples
Deck	6	deckNames, createDeck, getDeckStats, deleteDecks
Note	16	addNote, findNotes, notesInfo, updateNote, getTags
Card	19	findCards, getNextCards, cardsInfo, answerCards, suspend
Model	9	modelNames, modelFieldNames, createModel
Media	5	storeMediaFile, retrieveMediaFile, getMediaFilesNames
Stats	7	getNumCardsReviewedToday, getDueCardsDetailed
GUI	17	guiBrowse, guiAddCards, guiDeckReview
System	17	sync, exportPackage, importPackage, multi

Run npx anki-ai tools for the full list, or npx anki-ai tools --category deck to filter.

Key Features

• 96 tools covering all Anki-Connect operations
• CLI + MCP - Every tool available as both CLI command and MCP tool
• Pagination - offset/limit on all list operations
• Auto-batching - Operations >100 items split automatically
• Queue priority - getNextCards respects Learning > Review > New order
• Flexible input - Tags/IDs accept arrays, strings, or JSON
• TypeScript + Zod - Full type safety and schema validation

Configuration

Option	Description
--url <url>	Anki-Connect server URL
ANKI_CONNECT_URL	Environment variable (default: http://127.0.0.1:8765)
ANKI_API_KEY	Optional API key for Anki-Connect

Troubleshooting

"Cannot connect" or "Connection refused"

1. Ensure Anki is running (not just in background)
2. Verify Anki-Connect is installed: Tools → Add-ons
3. Check Anki-Connect is listening:

   curl localhost:8765 -d '{"action":"version","version":6}'

4. If using a different port, set ANKI_CONNECT_URL:

   export ANKI_CONNECT_URL=http://127.0.0.1:8766

Permission dialog on first connection

Anki-Connect shows a permission prompt when Anki-AI first connects. Click Yes to allow. If you clicked "No":

1. Go to Tools → Add-ons → AnkiConnect → Config
2. Add your app to corsOriginList

"AnkiConnect is not installed"

The add-on code is 2055492159. Verify installation in Tools → Add-ons.

macOS: Anki goes to sleep

Run this command to prevent App Nap:

defaults write net.ankiweb.dtop NSAppSleepDisabled -bool true

"CORS" or "Origin not allowed"

Add the requesting app to corsOriginList in Anki-Connect config.

Project Structure

anki-ai/
  bin/anki-ai.ts              # Bun development entry point
  src/
    main.ts                  # CLI entry point (compiles to dist/main.js)
    index.ts                 # MCP-only entry point
    shared/                  # Config, types, anki-connect client, normalization
    tools/                   # 96 tool definitions (8 category files)
    cli/                     # Commander.js subcommands
    mcp/                     # MCP server setup
  dist/                      # Compiled JS (shipped via npm)
  tests/                     # E2E integration tests

Development

Requires Bun for development:

bun install
bun run dev                  # Watch mode MCP server
bun test                     # Run all tests
bun run build                # Compile to dist/
bun run typecheck            # Type check only
bun run lint                 # Lint with Biome

Testing

Tests require Anki running with Anki-Connect installed:

bun test                     # All tests
bun test:e2e:basic           # Basic connectivity
bun test:e2e:tags            # Tag handling
bun test:e2e:pagination      # Pagination
bun test:e2e:queue           # Queue priority

Links

• Anki-Connect Docs
• MCP Specification
• Anki Forums
• Claude Desktop

License

MIT