Anki MCP

Multi-tenant, self-hosted Anki MCP server for AI-assisted flashcard generation.

Connect Claude (claude.ai, Claude Code, or any MCP client) to your own Anki collection. Claude adds cards for you — from any device — and they sync straight to AnkiMobile / AnkiDroid on your phone. It also surfaces weak-card analytics so Claude can target the cards you keep getting wrong.

Each user (authenticated via Keycloak) gets their own isolated Anki collection and sync slot. One deployment serves many people.

Why self-host? Your collection, your sync server, your data. Cards generated by an AI flow through a stack you control — no third-party flashcard SaaS.

What it is

• An MCP server (Python / FastMCP, streamable-HTTP) exposing Anki operations as tools Claude can call.

• Backed by the real anki library — it operates on genuine Anki collections, not a reimplementation, so everything round-trips through normal Anki sync.

• Fronted by a stock self-hosted Anki sync server, so your phone's AnkiMobile / AnkiDroid syncs against the same collection Claude writes to.

• Multi-tenant: per-user (Keycloak sub) tenants, each = an Anki collection + a sync slot, with secrets encrypted at rest in Postgres.

• A self-service portal (Next.js) where users provision their own tenant and get one-time sync credentials + phone setup instructions.

The core loop: add a card from claude.ai → it syncs to your phone.

Related MCP server: Anki MCP Server

Architecture / topology

                              Internet
                                 │
                                 │  HTTPS :443 (TLS 1.2 + 1.3)
                                 ▼
                       ┌───────────────────┐
                       │       Caddy       │   ← the ONLY public surface
                       │  (system service) │
                       └─────────┬─────────┘
            ┌────────────┬───────┴───────┬─────────────┐
            │ /mcp       │ /portal*      │ /sync*       │
            │ /.well-    │               │ /msync*      │
            │  known/*   │               │              │
            ▼            ▼               ▼              │
   ┌──────────────┐ ┌───────────┐ ┌──────────────────┐ │
   │   anki-mcp   │ │anki-portal│ │ anki-sync-server │ │
   │  FastMCP +   │ │ Next.js   │ │  (stock, AGPL)   │ │
   │  Keycloak JWT│ │ portal    │ │  SYNC_USERn pool │◄┘  AnkiMobile /
   │  per-tenant  │ └─────┬─────┘ └────────┬─────────┘    AnkiDroid sync
   │  AnkiStore   │       │                │              against the same
   └──────┬───────┘       │  /accounts API │              collection
          │  ⇅ sync       └───────────────►│
          │  (uploads/downloads collections)
          │                                ▲
          │  resolves tenant by sub        │
          ▼                                │
   ┌──────────────┐                        │
   │ anki-postgres│  tenant_accounts       │
   │  sub-scoped  │  (slot password        │
   │  AES-256-GCM │   encrypted, AAD=sub)  │
   └──────────────┘                        │
                                           │
   All internal ports bound to 127.0.0.1 ─┘  (see scripts/check-exposure.sh)

Identity flows JWT → sub → DB scope → AES-256-GCM (AAD=sub). Auth is single-realm; data is multi-tenant. See docs/SECURITY.md.

How it was built — phases

MCP tools

All tools take a tenant argument (the tenant alias; null resolves the user's default tenant). They operate on the caller's own collection only.

Quickstart (local)

Prerequisites: Docker + Docker Compose, and a reachable Keycloak realm named mcp (the default points at auth.ai.gerline.ru — change it for your own realm).

# 1. Configure
cp .env.example .env

# 2. Generate secrets into .env
#    ENCRYPTION_KEY (AES-256, 32 bytes / 64 hex):
openssl rand -hex 32        # -> ENCRYPTION_KEY=
#    NEXTAUTH_SECRET (portal session signing):
openssl rand -base64 32     # -> NEXTAUTH_SECRET=
#    Set POSTGRES_PASSWORD, the SYNC_USERn slot passwords, MCP_HOST, and the
#    Keycloak URLs in .env. (See .env.example comments.)

# 3. Bring the stack up
docker compose up -d

# 4. Verify nothing but Caddy faces the internet
bash scripts/check-exposure.sh   # must PASS

# 5. Provision your first tenant via the portal (behind Caddy at /portal),
#    capture the one-time sync credentials, and configure AnkiMobile.

For a real internet-facing deployment (VPS, Caddy as a system service, Keycloak clients, TLS, the slot pool, the ENFORCE_AUDIENCE=true cutover) follow the deploy runbook.

Documentation

• docs/DEPLOY.md — production deployment runbook.

• docs/SECURITY.md — the security model and residual risks.

• docs/HANDOFF.md — remaining manual/ops actions + the real end-to-end acceptance test.

License

AGPL-3.0. This project links the anki library and is fronted by the Anki sync server, both of which are AGPL-licensed, and it is served over a network — so the AGPL applies. The full text is in LICENSE. If you run a modified version as a network service, you must offer your users its source.