@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.1.0 — Initial MVP release. Safety-first, read-heavy toolset with dryRun support for writes.

Core Features

• Deck management — List and create decks (including hierarchical :: decks)
• Note operations — Add, search, update, and inspect notes
• Batch operations — Add multiple notes with per-item result tracking
• 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

Quick Start

# 1. Ensure Anki is running with AnkiConnect plugin installed
# 2. Install dependencies
npm install

# 3. Build
npm run build

# 4. Start the server
npm start

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}

Documentation

• Installation & Configuration — Setup, env vars, client config
• 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 test with MCP JSON Tester

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 |

See Tool Schema Reference for full input/output specs.

Client Configuration

Claude Desktop

{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["/absolute/path/to/anki-mcp/dist/index.js"]
    }
  }
}

Cursor / Cline

Same JSON format — add to your MCP server configuration.

npx (quick test)

npx @lifeng688/anki-mcp

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
• Dangerous operations (delete, sync, import, export) are not in v0.1.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. Never expose port 8765 to the network

Testing

See Testing Guide for full instructions.

npm run build
node run-mcp-json-test.mjs tests/anki/ping.json --verbose
node run-mcp-json-test.mjs tests/anki/check-anki-connection.json --verbose
# ... run all tests in tests/anki/

License

MIT — See LICENSE for details.