Anki MCP Server

A headless MCP server for Anki flashcards with Google OAuth authentication, deployed on Fly.io.

Features

• Deck Management — Create, list, and delete decks

• Card Operations — Add, update, query, suspend/unsuspend cards

• Model/Note Types — Manage note types, field configs, templates

• Tag Operations — Bulk add/remove tags

• Media Files — Store, retrieve, and delete media

• AnkiWeb Sync — Full collection + media sync

• Import/Export — Import and export .apkg packages

• Review Stats — Query due cards, intervals, scheduling info

• Google OAuth — Secure authentication with email allowlist

Related MCP server: TalkToAnki

Quick Start

Prerequisites

• Python 3.10+

• An AnkiWeb account (for sync)

• Google OAuth credentials

Install

cd anki-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

Configure Environment Variables

# Google OAuth (required)
export GOOGLE_CLIENT_ID="your-google-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Allowed users (comma-separated emails)
export ANKI_MCP_ALLOWED_EMAILS="user1@gmail.com,user2@gmail.com"

# AnkiWeb (optional, for sync)
export ANKIWEB_USERNAME="your@email.com"
export ANKIWEB_PASSWORD="your-password"

# Server config
export PORT=8000
export ANKI_MCP_BASE_URL="https://your-domain.com"

Run

anki-mcp

The server starts on port 8000 with:

• MCP endpoint at /mcp (streamable-http transport)

• Health check at /health

Authentication

The server uses Google OAuth via FastMCP. Only users whose emails are listed in ANKI_MCP_ALLOWED_EMAILS can access the server.

Google OAuth Setup

1. Create a Google Cloud project with an OAuth 2.0 Client ID

2. Add the redirect URI: https://your-app.fly.dev/auth/callback

3. Enable the Google+ API (for userinfo access)

4. Set the required scopes: openid, email

Deploy to Fly.io

# Create the app (first time)
fly apps create anki-mcp

# Set secrets
fly secrets set GOOGLE_CLIENT_ID="..."
fly secrets set GOOGLE_CLIENT_SECRET="..."
fly secrets set ANKI_MCP_ALLOWED_EMAILS="zephell@gmail.com,my.buddy.assistant@gmail.com"
fly secrets set ANKIWEB_USERNAME="..."
fly secrets set ANKIWEB_PASSWORD="..."

# Deploy
fly deploy

Available MCP Tools

Architecture

MCP Client → /mcp (streamable-http) → Google OAuth → Anki Tools → Anki Collection
                                         ↓
                                   Email Allowlist
                                         ↓
                                   anki Python package → collection.anki2

Development

# Run tests
source .venv/bin/activate
pytest

# Lint
ruff check src/ tests/

License

MIT