GitHub

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)

  1. Open Anki and go to Tools → Add-ons → Get Add-ons...
  2. Enter the addon code: 1513864660
  3. Click OK and restart Anki
  4. 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

  1. Download the latest release from GitHub
  2. Extract the archive
  3. 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/
  4. Restart Anki

Configuration

Anki Addon Settings

Configure AnkiMCP through Anki's addon configuration:

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

Configuration Options

ankimcp.json JSON
                        {
  "host": "localhost",
  "port": 8765,
  "global_permissions": {
    "read": true,
    "write": true,
    "delete": false
  },
  "deck_permissions": {
    "MyPrivateDeck": {
      "read": false,
      "write": false,
      "delete": false
    }
  },
  "protected_decks": ["ImportantDeck", "ExamPrep"]
}

MCP Host Configuration

Configure your MCP host to connect to AnkiMCP:

Claude Desktop

Edit ~/.config/claude-desktop/claude_desktop_config.json:

claude_desktop_config.json JSON
                        {
  "mcpServers": {
    "ankimcp": {
      "command": "python",
      "args": ["-m", "ankimcp"],
      "env": {
        "ANKIMCP_HOST": "localhost",
        "ANKIMCP_PORT": "8765"
      }
    }
  }
}

Other MCP Hosts

For custom MCP implementations, connect to:

  • Host: localhost (or configured host)
  • Port: 8765 (or configured port)
  • Protocol: MCP over stdio/HTTP

Capabilities

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

Deck Management

  • list_decks - Get all available decks
  • create_deck - Create new decks
  • delete_deck - Remove decks (with protection)
  • get_deck_stats - Retrieve deck statistics

Note Operations

  • search_notes - Search using Anki syntax
  • get_note_info - Detailed note information
  • create_note - Add new notes/cards
  • update_note - Modify existing notes
  • delete_notes - Remove notes (with protection)

Card Information

  • get_card_info - Individual card details
  • find_cards - Search for specific cards
  • get_card_reviews - Review history
  • suspend_cards - Suspend/unsuspend cards

Statistics & Analysis

  • get_collection_stats - Overall collection metrics
  • get_review_stats - Learning progress data
  • get_due_cards - Cards scheduled for review
  • get_learning_stats - Performance analytics

API Reference

Detailed reference for each MCP tool available in AnkiMCP:

list_decks

Returns all available decks with their IDs and configuration status.

Response Example:

list_decks JSON
                        [
  {
    "id": 1234567890,
    "name": "Japanese::Vocabulary",
    "newCount": 45,
    "reviewCount": 12,
    "totalCount": 892
  }
]

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

Response Example:

search_notes JSON
                        [
  {
    "noteId": 1234567890,
    "fields": {
      "Front": "こんにちは",
      "Back": "Hello"
    },
    "tags": ["vocabulary", "greetings"],
    "modelName": "Basic"
  }
]

create_note

Create a new note in the specified deck.

Parameters:

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

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-Specific Controls

Override permissions for individual decks:

deck_permissions JSON
                        "deck_permissions": {
  "PersonalDiary": {
    "read": false,    // Completely hidden
    "write": false,
    "delete": false
  },
  "WorkNotes": {
    "read": true,     // Read-only access
    "write": false,
    "delete": false
  }
}

Protected Decks

Add an extra layer of protection against accidental deletion:

protected_decks JSON
                        "protected_decks": [
  "MedicalSchool",
  "PhD Research",
  "CertificationExam"
]

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

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 8765 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 localhost:8765

Solutions:

  • Check if another application is using port 8765
  • Try changing the port in addon configuration
  • Verify localhost DNS resolution works
  • 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