playbooks

home / mcp / anki mcp server

Anki MCP Server

Provides an MCP server that enables AI assistants to interact with Anki for notes, decks, and media management.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "ankimcp-anki-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@ankimcp/anki-mcp-server",
        "--stdio"
      ],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765",
        "ANKI_CONNECT_API_KEY": "YOUR_API_KEY",
        "ANKI_CONNECT_TIMEOUT": "5000",
        "ANKI_CONNECT_API_VERSION": "6"
      }
    }
  }
}

You can connect AI assistants to Anki through a dedicated MCP server, enabling natural language interactions to manage notes, decks, and media. This server acts as a bridge between AnkiConnect-enabled Anki and MCP-powered assistants, so you can create, edit, search, and review content with conversational prompts.

How to use

Choose a transport mode based on how your AI assistant runs. Use STDIO for local desk-based assistants (recommended for Claude Desktop and similar clients) or HTTP for web-based assistants. Start by running the MCP server in one of the supported modes, then point your MCP client to the server using the provided configuration. You can perform actions like syncing with AnkiWeb, retrieving cards due for review, adding or updating notes, and managing media. For image handling, prefer file paths or URLs to keep transfers fast and token-efficient.

How to install

Prerequisites you need on your computer: a working Anki installation with AnkiConnect installed, and Node.js 20 or newer. Follow one of these options to get the MCP server running.

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}
{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Option 1: MCPB Bundle (Local Mode)

Best for Claude Desktop users. Download the latest .mcpb bundle, then install the extension in Claude Desktop via Settings > Extensions or Settings > Developer > Extensions.

Configure AnkiConnect if needed (defaults to http://localhost:8765) and restart Claude Desktop to start using the MCP server locally.

Option 2: NPM Package with STDIO (for other MCP clients)

You can run the server from your terminal using npx or a global install, then connect your MCP client in STDIO mode.

Using npx (no installation):

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Using a global installation:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Option 3: HTTP Mode (for remote AI assistants)

If you want to connect web-based assistants like ChatGPT or Claude.ai, run the server in HTTP mode to expose an MCP endpoint that your assistant can reach. You can optionally enable an ngrok tunnel to create a public URL.

Environment and startup tips

Common environment variable you will configure is ANKI_CONNECT_URL, which should point to your local AnkiConnect server. You can adjust the port and host for HTTP mode if you run the server directly, and you may enable an ngrok tunnel for public access when needed.

Connect to Claude Desktop (Local Mode)

In Claude Desktop you can configure the MCP server by adding a mcpServers entry to the Claude desktop config. Use the STDIO entry with the appropriate command and arguments to start the server locally.

Environment variables (optional)

The following variables can be configured to customize behavior. Provide example values where shown. If a variable is not specified here, use the defaults described in the setup guide.

ANKI_CONNECT_URL=http://localhost:8765
ANKI_CONNECT_API_VERSION=6
ANKI_CONNECT_API_KEY=YOUR_API_KEY
ANKI_CONNECT_TIMEOUT=5000

Usage examples

You can perform common actions like finding notes, updating fields, or deleting notes directly through natural language prompts. The server translates your requests into Anki actions via AnkiConnect, enabling a seamless learning workflow.

Known issues

Be mindful of notes being updated while you view them in Anki’s browser; this can cause updates to fail. Always switch away from the note in the browser before applying updates. For web mode, ensure CORS settings allow the client you are using.

Build and test commands

Build and run tasks include building TypeScript code, starting in different modes, and bundling into MCPB files for distribution. Use the following commands as needed in your development workflow.

Available tools

sync

Synchronize with AnkiWeb to ensure decks, notes, and media are up to date.

get_due_cards

Retrieve cards that are due for review from selected decks.

present_card

Display a card for review in the current session.

rate_card

Provide feedback on card performance to adapt future sessions.

list_decks

List available decks in your Anki collection.

createDeck

Create a new deck within Anki.

addNote

Create a new note in a specified deck with given fields.

findNotes

Search notes using Anki query syntax.

notesInfo

Get detailed information about notes including fields, tags, and CSS.

updateNoteFields

Update existing note fields with HTML/CSS-aware support.

deleteNotes

Delete notes and their associated cards, with explicit confirmation.

mediaActions

Manage media files including upload, retrieval, listing, and deletion.

storeMediaFile

Upload a media file from base64, a file path, or a URL.

retrieveMediaFile

Download a media file as base64.

getMediaFilesNames

List all media file names with optional pattern filtering.

deleteMediaFile

Remove a media file from your collection.

modelNames

List available note types (models) in your collection.

modelFieldNames

Get fields for a specific note type.

modelStyling

Retrieve CSS styling for a note type to ensure proper rendering.