Documentation - AnkiMCP

Overview

AnkiMCP is an Anki addon that bridges your flashcard collection with AI assistants through the Model Context Protocol (MCP). Unlike traditional REST APIs, MCP provides a standardized way for AI tools to access and interact with your data safely and efficiently.

AnkiMCP vs AnkiConnect

AnkiMCP Advantages

Built for AI assistant integration
MCP protocol standardization
Fine-grained permission system
Automatic server lifecycle management
Type-safe tool definitions

AnkiConnect Use Cases

Browser extensions (Yomichan, etc.)
Direct HTTP API integration
Legacy application support
Custom automation scripts

Installation

Method 1: AnkiWeb (Recommended)

Open Anki and go to Tools → Add-ons → Get Add-ons...
Enter the addon code: 1513864660
Click OK and restart Anki
The MCP server will start automatically when you open a profile

Tip: You can also browse the addon listing at ankiweb.net/shared/info/1513864660 to verify the code before installing.

Method 2: Manual Installation

Download the latest release from GitHub
Extract the archive
Copy the src/ankimcp folder to your Anki addons directory:
- Windows: %APPDATA%\\Anki2\\addons21\\
- macOS: ~/Library/Application Support/Anki2/addons21/
- Linux: ~/.local/share/Anki2/addons21/
Restart Anki

Configuration

Anki Addon Settings

Configure AnkiMCP through Anki's addon configuration:

Go to Tools → Add-ons
Select AnkiMCP and click Config
Modify settings as needed

Configuration Options

ankimcp.json JSON

                        {
  "host": "localhost",
  "port": 4473,
  "mode": "denylist",
  "global_permissions": {
    "read": true,
    "write": true,
    "delete": false
  },
  "deck_allowlist": [],
  "deck_denylist": ["PrivateDeck"],
  "protected_decks": ["Default", "ImportantDeck"],
  "protected_tags": [],
  "readonly_tags": ["readonly"],
  "note_type_permissions": {
    "allow_create": true,
    "allow_modify": false,
    "allowed_types": []
  }
}

MCP Host Configuration

Configure your MCP host to connect to AnkiMCP:

Claude Desktop / Claude Code

Add to your MCP configuration (e.g., .mcp.json or claude_desktop_config.json):

mcp.json JSON

                        {
  "mcpServers": {
    "ankimcp": {
      "type": "sse",
      "url": "http://localhost:4473/sse"
    }
  }
}

Other MCP Hosts

For custom MCP implementations, connect to:

URL: http://localhost:4473/sse
Protocol: MCP over SSE (Server-Sent Events)

Capabilities

AnkiMCP provides comprehensive access to your Anki collection through these MCP tools:

Deck Management

list_decks - Get all available decks
get_deck_info - Get detailed deck information
create_deck - Create new decks
update_deck - Rename or update deck properties
delete_deck - Remove decks (with protection)

Note Operations

search_notes - Search using Anki syntax
get_note - Get detailed note information
get_cards_for_note - Get cards for a note
create_note - Add new notes/cards
update_note - Modify existing notes
delete_note - Remove a note

Note Types

list_note_types - List available note types
create_note_type - Create custom note types

Statistics & Settings

get_review_stats - Learning progress data
get_permissions - View permission settings

API Reference

Detailed reference for each MCP tool available in AnkiMCP:

list_decks

Returns all available decks with their IDs and card counts.

Response Example:

list_decks JSON

                        [
  {
    "id": 1234567890,
    "name": "Japanese::Vocabulary",
    "card_count": 892,
    "is_filtered": false
  }
]

search_notes

Search notes using Anki's powerful search syntax.

Parameters:

query (string) - Anki search query (e.g., "deck:Japanese tag:vocabulary")
limit (number, optional) - Maximum results to return (default: 50)

Response Example:

search_notes JSON

                        [
  {
    "id": 1234567890,
    "model_name": "Basic",
    "fields": {
      "Front": "こんにちは",
      "Back": "Hello"
    },
    "tags": ["vocabulary", "greetings"],
    "card_count": 1
  }
]

create_note

Create a new note in the specified deck.

Parameters:

deck_name (string) - Target deck name
model_name (string) - Note type/model name
fields (object) - Field values as key-value pairs
tags (array, optional) - Tags to add to the note

Response Example:

create_note JSON

                        {
  "id": 1234567890,
  "model_name": "Basic",
  "fields": {
    "Front": "Hello",
    "Back": "World"
  },
  "tags": ["test"],
  "card_count": 1
}

get_deck_info

Get detailed information about a specific deck.

Parameters:

deck_name (string) - Name of the deck

Response Example:

get_deck_info JSON

                        {
  "id": 1234567890,
  "name": "Japanese::Vocabulary",
  "card_count": 892,
  "new_count": 45,
  "learning_count": 12,
  "review_count": 100,
  "is_filtered": false
}

update_deck

Update a deck's properties (rename or set description).

Parameters:

deck_name (string) - Current name of the deck
new_name (string, optional) - New name for the deck
description (string, optional) - New description

delete_deck

Delete a deck and all its cards. Cannot delete protected decks.

Parameters:

deck_name (string) - Name of the deck to delete

get_review_stats

Get review statistics for a deck or the entire collection.

Parameters:

deck_name (string, optional) - Deck name, or omit for all decks

Response Example:

get_review_stats JSON

                        {
  "deck_name": "All Decks",
  "total_cards": 5000,
  "new_cards": 1000,
  "learning_cards": 50,
  "review_cards": 500,
  "mature_cards": 3450
}

list_note_types

List all available note types (models) with their fields.

Response Example:

list_note_types JSON

                        [
  {
    "id": 1234567890,
    "name": "Basic",
    "fields": ["Front", "Back"],
    "templates": ["Card 1"],
    "field_count": 2,
    "template_count": 1
  }
]

get_permissions

Get current permission settings.

Response Example:

get_permissions JSON

                        {
  "mode": "denylist",
  "global_permissions": {
    "read": true,
    "write": true,
    "delete": true
  },
  "protected_decks": ["Default"],
  "deck_allowlist": [],
  "deck_denylist": []
}

Security & Permissions

AnkiMCP includes comprehensive security features to protect your Anki collection:

Global Permissions

Set default permissions for all operations:

Read: Allow viewing decks, notes, and statistics
Write: Allow creating and updating notes/decks
Delete: Allow removing notes and decks

Deck Access Control

Control which decks are accessible using allowlist or denylist mode:

deck_access JSON
                        "mode": "denylist",
"deck_allowlist": [],
"deck_denylist": ["PersonalDiary", "Private"]
                

In denylist mode, all decks are accessible except those listed. In allowlist mode, only listed decks are accessible.

Protected Decks

Add an extra layer of protection against accidental deletion:

protected_decks JSON
                        "protected_decks": [
  "Default",
  "MedicalSchool"
]
                

Protected decks cannot be deleted even if delete permissions are enabled.

Note Type Permissions

Control which note types can be used for creating notes:

note_type_permissions JSON
                        "note_type_permissions": {
  "allow_create": true,
  "allow_modify": false,
  "allowed_types": []
}
                

When allowed_types is empty with denylist mode, all types are allowed.

Troubleshooting

MCP Server Not Starting

Symptoms: AI assistant can't connect to AnkiMCP

Solutions:

Ensure Anki is running with a profile loaded
Check that the addon is enabled in Tools → Add-ons
Verify port 4473 is not blocked by firewall
Restart Anki and try again

Permission Denied Errors

Symptoms: "Permission denied" when AI tries to create/modify content

Solutions:

Check addon configuration for global permissions
Verify deck-specific permissions are not too restrictive
Ensure the target deck isn't in the protected list

Connection Refused

Symptoms: MCP host can't connect to http://localhost:4473/sse

Solutions:

Check if another application is using port 4473
Verify the SSE endpoint is accessible: curl http://localhost:4473/health
Try changing the port in addon configuration
Check system firewall settings

Getting Help

If you're still experiencing issues:

Check the GitHub issues for similar problems
Create a new issue with detailed error messages and your configuration
Include your Anki version and operating system