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

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

Create a Google Cloud project with an OAuth 2.0 Client ID
Add the redirect URI: https://your-app.fly.dev/auth/callback
Enable the Google+ API (for userinfo access)
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

Category	Tools
Decks	`get_deck_names`, `get_deck_names_and_ids`, `create_deck`, `delete_decks`, `get_deck_config`, `change_deck`
Models	`get_model_names`, `get_model_field_names`, `get_model_templates`, `get_model_styling`
Notes	`add_note`, `find_notes`, `get_notes_info`, `update_note_fields`, `delete_notes`, `cards_to_notes`
Cards	`find_cards`, `get_cards_info`, `suspend_cards`, `unsuspend_cards`, `are_suspended`, `are_due`, `get_card_intervals`
Tags	`get_all_tags`, `add_tags`, `remove_tags`
Media	`get_media_dir_path`, `store_media_file`, `store_media_file_from_path`, `retrieve_media_file`, `delete_media_file`
Sync	`do_sync`, `do_sync_media`, `get_sync_status`
Import/Export	`import_package`, `export_package`
Utility	`get_api_version`

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

anki-mcp