Anki Model Context Protocol (MCP) Server

고성능 Model Context Protocol (MCP) 서버로, AI 어시스턴트(Claude Desktop, Claude Code, Antigravity, Codex, Cursor 등)가 Anki 플래시카드, 덱, 노트타입, 태그, 미디어, 검색을 직접 관리할 수 있게 합니다.

⚡ 유니버설 파일 기반 I/O 아키텍처

현대 플래시카드(특히 HTML 마크업, 구문 하이라이트 코드 블록, LaTeX 수식)는 페이로드가 큽니다. 이들을 JSON-RPC 도구 파라미터로 스트리밍하거나 전체 카드 내용을 모델에 직접 반환하면 토큰이 고갈되고, 출력이 잘리며, 콘텍스트 윈도우가 포화됩니다.

이 서버는 **Universal File-Based Input and Output (File-Based I/O)**를 구현합니다:

1. 인밴드 토큰 팽창 제로: 플래시카드 변경, 쿼리, 검색, 스키마 내부 구조는 입력 JSON 파일 경로를 받고 전체 구조 출력을 간디스크에 저장합니다.

2. 컴팩트 텔레메트리 응답: 모든 도구 호출은 상태, ID, 영향받은 수, 결정된 output_file 경로가 포함된 제한된 메타데터 요약($< 150$ 토큰)을 반환합니다.

3. 원자 배치 투입: 수백 개의 카드를 단일 JSON 파일 페이로드로 기록하고, 단일 SQLite 트랜잭션에서 원자적으로 밀리초 단위에 도입합니다.

4. 크로스 -플랫트폼 임시 저장소: 출력은 기본적으로 %TEMP%\anki_mcp (Windows) 또는 Linu//ankimcp(Linux/macOS)에 저장되며, 우선ANKI_MCP_OUTPUT_DIR`로 재정의할 수 있습니다.# from here

Related MCP server: Anki MCP Server

특징

• ⚡ 빠른 직속 연결: HTTP 부담 없이 공식 anki Python 엔진을 통해 Anki의 컬렉션 디렵베(collection.anki2))와 직접 상호작용합니다.

• 🔒 비블로킹 연결 수🍟명: 요청당 분리된 컬텍스트 관리(약 2.m` 2.7ms)로 DB학제가 즉시 해제되어 Anki Desktop을 잠그하지 않습니다.

• ** 크로스 플랫트폼:** Windows, macOS, Linux를 기반으로 표준 OS 위치에서 컬렉션을 자동 페색합니다.

• 🗂️ 계층적 덱: Computer Science::Algorithms::Trees처럼 중첩된 덱 생성을 완전 지원합니다.

• **📝🐴 리치 카드: Standard/Basic, Cloze deletions (){{c1::...}}), 사용자 지정 필드, LaTeX 수식 ($...$ 및 $$...$$)을 지원합니다.

• 🔍 쿼리 엔진: Anki 검색 구문(deck:Language:Science, tag:grammar, is:due, added:7, "Recursion")을 완전 지원합니다.

• 🏷 태그 관리: 계층 구조 태그와 태그 일괄 추가/제거을 지원합니다.

• 📦 배치 생생성: JSON 페이로드를 이용해 단일 원자작업으로 고속 / 일괄 카드 추가합니다.

• 💾 Deex Export: .apkg, .colpkg, .json 형식으로 패키징합니다.

• 💡 MCP Prмпt & Resource: 내장 전원 (anki://decks, anki://stats) 및 구조화된 카드 생성 프롬트 (flashcard_generator).

Installation & Setup

이 프로젝트는 빠르고 재현 가능한 Python 환경 구성을 위해 uv 를 사용합니다.

Clone and Install

git clone https://github.com/debnath-d/anki-mcp-server.git
cd anki-mcp-server
uv sync

Run Server

서버 실:

uv run anki-mcp-server

Client Encrin Figuration

1. Claude Desktop

Claude D Desktop 구성 파일에 서버를 추가합니다:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Windows Configuration

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\anki-mcp-server",
        "run",
        "anki-mcp-server"
      ]
    }
  }
}

macOS / Linux Configuration

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/anki-mcp-server",
        "run",
        "anki-mcp-server"
      ]
    }
  }
}

2. Google Anti Gravity

Antigravity MCP configurations (~/.config/gemmine/config/mCP_config.json)에 serv에 추가:

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/anki-mcp-server",
        "run",
        "anki-mcp-server"
      ]
    }
  }
}

3. Claude Code / Codex / CLI Clients

Claude Code로 MCP 서버를 실행:

claude --mcp-server "uv --directory '/path/to/anki-mcp-server' run anki-mcp-server"

Available MCP Tools

1. Deck Management

| Tool | Parameters | Description | | ------------- | ------------------------------------------------------------------------------------------------ | —------------------------------------------------------------------------------------------------ | | list_decks | output_file?: str | 모든 덱과 이름, ID, 카드 수를 나열하고, 계층 구조를 이스크에 저장 후 요약을 반환합니다. | | create_ck | deck_name: str, output_file?: string | 신규 덱 또는 하위 덱(예: Computer Science::알gorithms)를 생성합니다. | | rename_ck | deck_id: int, new_name: string, output_file?: string | 존재하는 덱의 이름을 바꾸고, 모든 하위 덱의 접미사를 입력하도록 바니다. | | delete_ck | deck_id: int?, deck_name: string?, output_file?: string | 덱와 카드를 삭제합니다. | | change_ck | target_deck_name?: string?, card_ids?: list[int], note_ids?: list[int], query?: string?, input_file?: string?, out_put_file?: string | 특정 ID, 리, 또는 입력 파일을 기준으로 카드를 다른 덱로 이동합니다. |

2. Notetypes (Model)

| Tool | Parameters | Description | | --- | --- | —------------------------------------- | | list_notetypes | output_file?: string | 사용가능한 모든 노트타입(예: Basic, Cloze)과 필드를 이파일에 저장합니다. | | get_notetype_info | notetype_name: string, output_file?: string | 특정 노트타입의 스키마, 필드, 텀플릿을 디스크에 저장합니다. |

3. Flashcard & Note Management (File-Based)

| Tool | Parameters | Description | | ---- | ----------------------------------------------- | ...-------------------------------------------------------------------- | | add_note | input_file: string, deck_name?: string, output_file?: string | JSON 파일 페이드({deck_name, front, fields, field, text, tagis, utiled})로 일반 노트를 생성합니다. | | add_cloze_note | input_file: string, deck_name?: string, output_file?: string | JSON 파일 페이드({... | | add_notes_batch | input_file: string, output_file?: string | JSON 배열 파일에서 여러 플래시카드를 단일 원자 베치로 추가합니다. | | get_note | note_id: int, output_file?: string | 노트 ID의 필드, 태그, 노트타입, 카드를 디스크에 저장합니다. | | update_note | note_id: int, input_file: string, output_file?: string | JSON 페이로드로 기존 노트의 필드/태그를 필할합니다. | | delete_notes | note_ids?: list[int], input_file?: string, output_file?: string | ID list 또는 JSON 파일로 노트와 카드를 삭제합니다. |

4. Media, State Control & Export

5. Search & Discovery

6. Tag Management & Stats

Testting

자동화 테스트 스위트와 린터를 실행:

ruff check .
uv run python -m unittest discover -s tests

Important Notes & Troubleshooting

1. SQLite 데이터베이스 잠금: Anki는 배타적 파일 잠금을 사용합니다. MCP 서버가 쓰기 작업을 실행하는 동안 anki.errors.DBError 잠금을 방지하려면 Anki 데스크톱 GUI 애플리케이션이 닫혀 있어야 합니다.

2. 컬렉션 경로 자동 감지:

   • Windows: %APPDATA%\Anki2\<Profile>\collection.anki2 또는 %LOCALAPPDATA%\Anki2\<Profile>\collection.anki2에서 자동으로 감지됩니다.

   • macOS: /Users/<사용자명>/Library/Application Support/Anki2/<Profile>/collection.anki2에서 자동으로 감지됩니다.

   • Linux: ~/.local/share/Anki2/<Profile>/collection.anki2에서 자동으로 감지됩니다.

   • 사용자 지정 위치를 사용하려면 ANKI_COLLECTION_PATH 환경 변수를 설정하세요.

3. 출력 캐시: 도구 출력은 기본적으로 OS 임시 디렉터리(%TEMP%\anki_mcp 또는 /tmp/anki_mcp)에 저장됩니다. 사용자 지정 디렉터리를 사용하려면 ANKI_MCP_OUTPUT_DIR을 설정하세요.