@Lifeng688/Anki

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.