@lifeng688/anki-mcp

MCP stdio server for controlling local Anki via AnkiConnect. Enables LLMs (Claude, Cursor, Cline) to manage Anki decks and notes through a standardized tool interface.

v0.2.0 — Controlled write operations with safe defaults (dryRun), tag management, and explicit sync confirmation.

Quick Install

npm install @lifeng688/anki-mcp

Or try it instantly:

npx @lifeng688/anki-mcp

Related MCP server: TalkToAnki

Prerequisites

1. Anki desktop installed

2. AnkiConnect add-on (code 2055492159) — install via Tools → Add-ons → Get Add-ons

3. Node.js >= 18.0.0

Verify AnkiConnect is running:

curl -X POST http://127.0.0.1:8765 \
  -H "Content-Type: application/json" \
  -d '{"action":"version","version":6}'
# Expected: {"result":6,"error":null}

Core Features

• Deck management — List and create decks (including hierarchical :: decks)

• Note operations — Add, search, update, delete, and inspect notes

• Tag management — Add and remove tags on notes by ID or search query

• Batch operations — Add multiple notes with per-item result tracking

• Safe note deletion — Delete notes with dryRun preview and explicit confirmation

• Explicit sync — Trigger AnkiCloud sync with confirmation guard

• Controlled writes — All mutation tools default to dryRun=true

• Safety first — dryRun support for batch writes, duplicate prevention, field validation

• Unified responses — Consistent success/error envelope across all tools

• Security-focused — Localhost only, no DB access, no card content logging

Available Tools

See Tool Schema Reference for full input/output specs.

MCP Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["$(npm root)/@lifeng688/anki-mcp/dist/index.js"]
    }
  }
}

With environment variables:

{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["$(npm root)/@lifeng688/anki-mcp/dist/index.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://127.0.0.1:8765",
        "ANKI_CONNECT_VERSION": "6",
        "ANKI_DEFAULT_DECK": "Default::MCP",
        "ANKI_DEFAULT_MODEL": "Basic",
        "ANKI_LOG_LEVEL": "warn"
      }
    }
  }
}

Note: Replace $(npm root)/@lifeng688/anki-mcp/dist/index.js with the actual resolved path. You can find it with:

npm root -g
# or
npm root

Cursor / Cline

Same JSON format — add to your MCP server configuration. Point args to the installed dist/index.js inside the @lifeng688/anki-mcp package directory.

Global Install

npm install -g @lifeng688/anki-mcp

Then configure your client to point to:

<global-npm-root>/@lifeng688/anki-mcp/dist/index.js

Environment Variables

URL Resolution Priority:

1. ANKI_CONNECT_URL — if set, used as-is (must point to localhost)

2. ANKI_CONNECT_HOST + ANKI_CONNECT_PORT — composed as http://{HOST}:{PORT}

3. http://127.0.0.1:8765 — hardcoded default

Security

• This server only connects to http://127.0.0.1:8765 (localhost)

• It does not read/write Anki SQLite databases directly

• It does not upload any data externally

• ANKI_CONNECT_KEY is never logged

• delete_notes defaults to dryRun=true; real deletion requires confirm="DELETE_NOTES"

• sync_anki defaults to dryRun=true; real sync requires confirm="SYNC_ANKI"

• add_tags / remove_tags default to dryRun=true

• import/export are not in v0.2.0

First-Time Setup

1. Create a Test::MCP deck before making real changes

2. Run ping and check_anki_connection to verify connectivity

3. Use add_notes with dryRun: true to preview before writing

4. Before deleting notes, always run delete_notes with dryRun: true first

5. Before batch tag operations, run add_tags / remove_tags with dryRun: true first

6. sync_anki requires explicit confirm="SYNC_ANKI" for real sync

7. Never expose port 8765 to the network

Documentation

• Installation & Configuration — Full setup guide

• Tool Schema Reference — All tools: input/output/examples/errors

• Roadmap — Feature progression plan (v0.1 → v0.6)

• Security Guide — Boundaries, risks, safety policies

• Conversation Quality Guide — How LLMs should create cards

• Testing Guide — How to run the test suite

License

MIT — See LICENSE for details.