Anki MCP 卡片管理服务

Anki MCP Server (Codemode)

An MCP server for AI-powered Anki interaction using a codemode architecture — the AI writes TypeScript code that executes against an injected anki API.

Why Codemode?

This server implements the codemode pattern pioneered by Cloudflare: instead of exposing dozens of discrete MCP tools, we provide a TypeScript API that the AI writes code against.

"LLMs are better at writing code to call APIs than at calling tools directly"

LLMs have been trained on billions of lines of real code, but relatively few synthetic tool-calling examples. Writing await anki.notes.add({...}) is natural — it's just TypeScript.

Benefits:

• Composable — Chain operations without round-trips through the LLM
• Efficient — Results flow through code, not back through the model for each step
• Familiar — Standard patterns the AI already knows from training data

Tools Overview

Prerequisites

• Anki desktop app (must be running)
• AnkiConnect plugin installed in Anki
• Bun runtime

Installation

git clone https://github.com/youruser/anki-mcp-codemode
cd anki-mcp-codemode
bun install

Claude Desktop / MCP Clients

Add to your MCP configuration:

{
  "mcpServers": {
    "anki": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/anki-mcp-codemode/src/index.ts"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Configuration

Remote Usage (HTTP Transport)

Run the server over Streamable HTTP instead of stdio:

MCP_TRANSPORT=http MCP_HTTP_TOKEN=your-secret bun run src/index.ts
# → http://127.0.0.1:8766/mcp  (health check at /health)

Connect from Claude Code:

claude mcp add --transport http anki http://your-host:8766/mcp \
  --header "Authorization: Bearer your-secret"

Notes for remote deployment:

• The server needs a reachable AnkiConnect, which means a running Anki. On a headless VPS, run Anki Desktop with QT_QPA_PLATFORM=offscreen and the AnkiConnect addon bound to a reachable address (community Docker images: ankimcp/headless-anki, ThisIsntTheWay/headless-anki).
• The HTTP transport runs stateless (fresh session per request, JSON responses), which suits a single-user server behind a VPN/Tailscale.
• Executed code runs in-process with no sandbox — treat the bearer token as full control over the machine, not just the Anki collection, and keep the port off the public internet.

Selective Tool Loading

Only enable the tools you need:

{
  "env": {
    "ANKI_TOOLS": "create,review"
  }
}

Usage Examples

Creating Cards

// List available decks and models
const decks = await anki.decks.list();
const models = await anki.models.list();
console.log({ decks, models });

// Create a deck and add cards
await anki.decks.create("Spanish Vocabulary");

const noteId = await anki.notes.add({
  deckName: "Spanish Vocabulary",
  modelName: "Basic",
  fields: { Front: "Hola", Back: "Hello" },
  tags: ["greeting", "beginner"]
});

console.log({ created: noteId });

Batch Operations

// Add multiple cards efficiently
const vocab = [
  { front: "perro", back: "dog" },
  { front: "gato", back: "cat" },
  { front: "pájaro", back: "bird" },
];

const noteIds = await anki.notes.addMany(
  vocab.map(v => ({
    deckName: "Spanish Vocabulary",
    modelName: "Basic",
    fields: { Front: v.front, Back: v.back }
  }))
);

// null marks a note AnkiConnect refused, usually a duplicate
console.log({ added: noteIds.filter(id => id !== null).length });

Study Session Prompts

// Get the twenty rules prompt for effective card creation
const rules = anki.prompts.twentyRules();
console.log(rules);

API Reference

See docs/API.md for the complete API documentation for each tool.

Development

bun install              # Install dependencies
bun run src/index.ts     # Run server
bun test                 # Run tests
bunx tsc --noEmit        # Type check

How It Works

1. MCP client sends TypeScript code to one of the 4 tools
2. Server executes the code with an injected anki object (in-process — trusted-client model, not a security sandbox)
3. The anki object provides type-safe methods that call AnkiConnect
4. console.log() output is captured and returned to the AI

┌─────────────┐     TypeScript      ┌─────────────┐     HTTP      ┌─────────────┐
│  AI Agent   │ ──── code ────────▶ │  MCP Server │ ────────────▶ │ AnkiConnect │
│  (Claude)   │ ◀─── console.log ── │    (Bun)    │ ◀──────────── │   (Anki)    │
└─────────────┘                     └─────────────┘               └─────────────┘

Attribution

This project was inspired by and builds upon concepts from @anthropics/anki-mcp-server (formerly anki-mcp-http). While the implementation is a complete rewrite using a different architecture (Bun + codemode vs NestJS + discrete tools), credit goes to the original authors for pioneering Anki + MCP integration.

License

MIT — Use freely, attribution appreciated.

Third-Party Notices

• Anki® is a registered trademark of Ankitects Pty Ltd. This is an unofficial third-party tool.
• Model Context Protocol (MCP) is an open standard by Anthropic.