@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

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

| Tool | Description | Side Effects | |---|---|---| | ping | Server health check | None | | check_anki_connection | Verify AnkiConnect reachable | None | | list_decks | List all decks | None | | create_deck | Create a new deck | Creates deck | | list_note_models | List note models | None | | get_note_model_fields | Get model fields | None | | add_note | Add single note | Creates note | | add_notes | Batch add notes | Creates notes | | search_notes | Search notes | None | | get_notes_info | Get note details | None | | update_note_fields | Update note fields | Modifies note | | delete_notes | Delete notes by ID or query | Deletes notes (requires confirm) | | add_tags | Add tags to notes | Modifies note tags | | remove_tags | Remove tags from notes | Modifies note tags | | sync_anki | Trigger AnkiCloud sync | Triggers network sync (requires confirm) |

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

| Variable | Default | Description | |---|---|---| | ANKI_CONNECT_URL | (none) | Full AnkiConnect HTTP endpoint (highest priority). Overrides HOST:PORT. | | ANKI_CONNECT_HOST | 127.0.0.1 | Host part, used when ANKI_CONNECT_URL is not set. | | ANKI_CONNECT_PORT | 8765 | Port part, used when ANKI_CONNECT_URL is not set. | | ANKI_CONNECT_VERSION | 6 | AnkiConnect API version | | ANKI_CONNECT_KEY | (empty) | AnkiConnect API key (if configured) | | ANKI_DEFAULT_DECK | Default | Default deck for note operations | | ANKI_DEFAULT_MODEL | Basic | Default note model | | ANKI_REQUEST_TIMEOUT_MS | 10000 | HTTP request timeout in milliseconds | | ANKI_LOG_LEVEL | info | Log verbosity: error / warn / info / debug |

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.