Anki MCP

공식

AI 어시스턴트가 간격 반복 플래시카드 애플리케이션인 Anki와 상호작용할 수 있게 해주는 MCP 서버입니다.

GitHub
370

Anki MCP(으)로 무엇을 할 수 있나요?

  • Review due cards in a specific deck — 어시스턴트에게 get_due_cards와 present_card를 사용하여 복습할 카드를 불러와 보여주도록 요청한 후, rate_card로 평가를 기록하세요.
  • Batch-create flashcards from a list — 용어와 정의 목록을 제공하면 어시스턴트가 addNotes를 통해 한 번에 최대 100개의 노트를 생성합니다.
  • Search and update existing notes — Anki 쿼리 구문을 사용하여 findNotes로 노트를 검색하고, notesInfo로 내용을 확인한 후, updateNoteFields로 필드를 수정하세요.
  • Manage note types and styling — createModel로 새로운 노트 유형을 만들고, updateModelStyling으로 CSS를 조정하거나, updateModelTemplates로 카드 템플릿을 수정하세요.
  • Import media files into your collection — 로컬 경로나 URL에서 storeMediaFile을 사용하여 이미지나 오디오 파일을 업로드하고, 노트 필드에서 참조하세요.

문서

Anki MCP 서버

Tests npm version

Anki + MCP Integration

모델 컨텍스트 프로토콜을 통해 Anki를 AI 어시스턴트와 원활하게 통합하세요

베타 - 이 프로젝트는 활발히 개발 중입니다. API와 기능은 변경될 수 있습니다.

AI 어시스턴트가 간격 반복 플래시카드 애플리케이션인 Anki와 상호 작용할 수 있게 해주는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

자연어 상호 작용으로 Anki 경험을 변화시켜 보세요. 마치 개인 교사와 함께하는 것과 같습니다. AI 어시스턴트는 단순히 질문과 답변을 제시하는 데 그치지 않고, 개념을 설명하고, 학습 과정을 더욱 흥미롭고 인간답게 만들며, 맥락을 제공하고, 학습 스타일에 적응할 수 있습니다. 즉석에서 노트를 생성하고 편집하여 학습 세션을 역동적인 대화로 바꿀 수 있습니다. 더 많은 기능이 곧 제공될 예정입니다!

예제 및 튜토리얼

Claude Desktop에서 이 MCP 서버를 사용하는 방법에 대한 포괄적인 가이드, 실제 예제, 단계별 튜토리얼을 보려면 다음을 방문하세요:

ankimcp.ai - 실용적인 예제와 사용 사례가 포함된 완전한 문서

검토자 설정 가이드와 샘플 Anki 덱을 포함한 보충 문서는 docs/을 참조하세요.

사용 사례 예시

이 서버가 가능하게 하는 도구 흐름을 보여주는 세 가지 대표적인 프롬프트:

  1. "내 스페인어 덱 복습을 도와줘." — 어시스턴트가 AnkiWeb과 동기화하고(sync), 예정된 카드를 가져오고(get_due_cards, 덱 필터 포함), 각 카드를 제시하고(present_card), 평가를 기록합니다(rate_card). 사용자에게 맞춤화된 설명이 포함된 자연스러운 학습 대화.

  2. "RTL 스타일의 아랍어 어휘 카드 10개를 만들어 줘." — 어시스턴트가 노트 유형을 나열하고(modelNames), 필요한 경우 사용자 정의 RTL 모델을 생성하고(createModel + 오른쪽에서 왼쪽 CSS를 위한 updateModelStyling), 카드를 일괄 생성합니다(addNotes).

  3. "내 다운로드 폴더에서 이 이미지를 선택된 노트의 앞면으로 가져와 줘." — 어시스턴트가 로컬 파일을 업로드하고(storeMediaFile, 파일 경로 포함), 브라우저에서 현재 선택된 노트를 읽고(guiSelectedNotes + notesInfo), 앞면 필드를 <img> 태그로 업데이트합니다(updateNoteFields).

사용 가능한 도구

이 서버는 42개의 MCP 도구를 제공합니다 — 일상적인 Anki 작업을 위한 31개의 필수 도구와 노트 편집/생성 워크플로우를 위해 Anki 데스크톱 인터페이스를 구동하는 11개의 GUI 도구.

필수 도구

복습 및 학습

  • sync - 최신 데이터를 가져오고 변경 사항을 푸시하기 위해 AnkiWeb과 동기화
  • get_due_cards - 복습 예정인 카드 가져오기, 선택적으로 덱으로 필터링
  • get_cards - 상태(예정, 새 카드, 학습 중, 일시 중지, 숨김) 및 덱별로 유연하게 필터링하여 카드 가져오기
  • present_card - 질문/앞면과 함께 복습용 카드 표시
  • rate_card - 카드 성과 평가(Again, Hard, Good, Easy) 및 다음 복습 일정 예약

덱 관리

  • listDecks - 모든 덱 나열, 선택적으로 덱별 카드 수 통계 포함
  • deckStats - 단일 덱에 대한 종합 통계 가져오기(개수, ease/간격 분포)
  • createDeck - 새 빈 덱 생성(Parent::Child 지원, 최대 2단계)
  • changeDeck - 카드를 다른 덱으로 이동(존재하지 않으면 생성)

노트 관리

  • addNote - 지정된 필드와 태그로 단일 노트 생성
  • addNotes - 덱과 모델을 공유하는 최대 100개의 노트 일괄 생성(부분 성공 지원)
  • findNotes - Anki 쿼리 구문을 사용하여 노트 검색(deck:, tag:, is:due 등)
  • notesInfo - 노트에 대한 자세한 정보 가져오기(필드, 태그, CSS 스타일링)
  • updateNoteFields - 기존 노트 필드 업데이트(CSS 인식, HTML 콘텐츠 지원)
  • deleteNotes - 노트 및 관련된 모든 카드 삭제(파괴적 작업, 확인 필요)

태그 관리

  • getTags - 컬렉션의 모든 태그 가져오기(중복 방지를 위해 먼저 사용)
  • addTags - 지정된 노트에 공백으로 구분된 태그 추가
  • removeTags - 지정된 노트에서 공백으로 구분된 태그 제거
  • replaceTags - 지정된 노트에서 태그 이름 변경
  • clearUnusedTags - 어떤 노트에서도 사용되지 않는 고아 태그 제거(파괴적 작업)

미디어 관리

  • getMediaFilesNames - collection.media의 미디어 파일 나열, 선택적으로 패턴으로 필터링
  • retrieveMediaFile - 미디어 파일을 base64 콘텐츠로 다운로드
  • storeMediaFile - base64 데이터, 절대 파일 경로 또는 URL에서 미디어 업로드
  • deleteMediaFile - collection.media에서 미디어 파일 제거(파괴적 작업)

💡 이미지 모범 사례:

  • ✅ 파일 경로 사용 (예: /Users/you/image.png) - 빠르고 효율적
  • ✅ URL 사용 (예: https://example.com/image.jpg) - 직접 다운로드
  • ❌ base64 피하기 - 매우 느리고 토큰 비효율적

Claude에게 이미지 위치를 알려주기만 하면 가장 효율적인 방법을 사용하여 자동으로 업로드를 처리합니다.

모델/템플릿 관리

  • modelNames - 사용 가능한 모든 노트 유형/모델 나열
  • modelFieldNames - 특정 노트 유형의 필드 이름 가져오기
  • modelStyling - 노트 유형의 CSS 스타일링 정보 가져오기
  • modelTemplates - 노트 유형의 카드 템플릿(앞면 및 뒷면 HTML) 가져오기
  • createModel - 사용자 정의 필드, 카드 템플릿, CSS로 새 노트 유형 생성(예: RTL 모델)
  • updateModelStyling - 기존 노트 유형의 CSS 스타일링 업데이트(모든 카드에 적용)
  • updateModelTemplates - 기존 노트 유형의 카드 템플릿(앞면 및 뒷면 HTML) 업데이트(모든 카드에 적용)
  • addModelField - 기존 노트 유형에 새 필드 추가(끝에 추가되거나 특정 위치에 삽입)
  • removeModelField - 기존 노트 유형에서 필드 제거(모든 노트에서 해당 콘텐츠 삭제, 명시적 확인 필요)
  • renameModelField - 기존 노트 유형의 필드 이름 변경(이전 이름을 참조하는 카드 템플릿은 별도로 업데이트해야 함)
  • repositionModelField - 기존 노트 유형 내에서 필드 위치 변경

통계

  • collection_stats - 덱별 분석과 함께 모든 덱에 걸친 집계 통계
  • review_stats - 복습 이력 분석(시간적 패턴, 유지율 지표, 학습 연속 기록)

GUI 도구

Anki 데스크톱 인터페이스를 구동하는 도구입니다. 노트 편집/생성 및 덱 관리 워크플로우를 위한 것이며, 복습 세션용이 아닙니다.

  • guiBrowse - 카드 브라우저를 열고 카드 검색
  • guiSelectCard - 카드 브라우저에서 특정 카드 선택
  • guiSelectedNotes - 카드 브라우저에서 현재 선택된 노트의 ID 가져오기
  • guiAddCards - 미리 설정된 노트 세부 정보로 카드 추가 대화 상자 열기
  • guiEditNote - 특정 노트의 노트 편집기 열기
  • guiDeckOverview - 특정 덱의 덱 개요 대화 상자 열기
  • guiDeckBrowser - 덱 브라우저 대화 상자 열기
  • guiCurrentCard - 복습 모드에서 현재 카드 정보 가져오기
  • guiShowQuestion - 현재 카드의 질문 면 표시
  • guiShowAnswer - 현재 카드의 답변 면 표시
  • guiUndo - Anki에서 마지막 작업 실행 취소

전제 조건

설치

서버를 머신에 설치하는 몇 가지 방법이 있습니다. 설치가 완료되면 AI 클라이언트 연결하기로 이동하여 AI 어시스턴트에 로컬 또는 원격으로 연결하세요.

npm (글로벌 또는 npx)

서버를 직접 실행하는 모든 MCP 클라이언트에 적합한 범용 설치 방법입니다.

ankimcp 명령을 실행하는 클라이언트를 위해 글로벌로 설치하세요:

npm install -g @ankimcp/anki-mcp-server

또는 설치 없이 필요할 때 실행하세요:

npx @ankimcp/anki-mcp-server

MCPB 번들 (Claude Desktop에 권장)

Claude Desktop용으로 이 MCP 서버를 설치하는 가장 쉬운 방법:

  1. Releases 페이지에서 최신 .mcpb 번들을 다운로드하세요.
  2. Claude Desktop에서 확장 프로그램을 설치하세요:
    • 방법 1: 설정 → 확장 프로그램으로 이동하여 .mcpb 파일을 드래그 앤 드롭
    • 방법 2: 설정 → 개발자 → 확장 프로그램 → 확장 프로그램 설치로 이동하여 .mcpb 파일 선택
  3. 필요한 경우 AnkiConnect URL 구성 (기본값: http://localhost:8765)
  4. Claude Desktop 재시작

이게 전부입니다! 번들에는 서버를 로컬에서 실행하는 데 필요한 모든 것이 포함되어 있습니다.

Anthropic MCP 디렉토리 검토자용: 미리 채워진 샘플 덱을 사용한 제로부터 통합까지의 연습 과정이 docs/reviewer-setup.md에 있습니다.

소스에서 설치 (개발용)

개발 또는 고급 사용을 위해:

npm install
npm run build

AI 클라이언트 연결하기

AI 어시스턴트가 실행되는 위치에 따라 이 서버에 연결하는 두 가지 방법이 있습니다:

  • 로컬 — 서버가 AI 클라이언트(Claude Desktop, Cursor, Cline, Zed 또는 로컬 브라우저 세션)와 동일한 머신에서 실행됩니다. 데스크톱 MCP 클라이언트에는 STDIO를, 로컬 웹 기반 도구에는 HTTP를 사용하세요.
  • 원격 — 호스팅된/원격 AI(예: 클라우드의 ChatGPT 또는 Claude.ai)가 로컬 머신에서 실행 중인 Anki에 연결해야 합니다. 관리형 터널(✅ 권장 — 인증됨)을 사용하거나, 더 가벼운 비인증 대안으로 ngrok을 사용하세요.

로컬

서버가 AI 클라이언트와 동일한 컴퓨터에서 실행되며 localhost에서 AnkiConnect와 통신합니다.

STDIO (기본 로컬 통합)

STDIO는 로컬 데스크톱 MCP 클라이언트(Claude Desktop, Cursor IDE, Cline, Zed Editor 등)를 위한 표준 전송 방식입니다. 클라이언트가 서버를 하위 프로세스로 실행하고 표준 입출력을 통해 통신합니다.

지원 클라이언트:

  • Claude Desktop
  • Cursor IDE - AI 기반 코드 편집기
  • Cline - AI 지원을 위한 VS Code 확장 프로그램
  • Zed Editor - 빠르고 현대적인 코드 편집기
  • STDIO 전송을 지원하는 기타 MCP 클라이언트

Claude Desktop의 경우 MCPB 번들이 가장 쉬운 방법입니다. 다른 클라이언트의 경우 --stdio 플래그로 npm 패키지를 구성하세요.

구성 - 방법 중 하나를 선택하세요:

방법 1: npx 사용 (권장 - 설치 불필요)

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

방법 2: 글로벌 설치 사용

먼저 글로벌로 설치하세요:

npm install -g @ankimcp/anki-mcp-server

그런 다음 구성하세요:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

구성 파일 위치:

  • Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) 또는 %USERPROFILE%\.cursor\mcp.json (Windows)
  • Cline: VS Code의 설정 UI를 통해 접근 가능
  • Zed Editor: 확장 마켓플레이스를 통해 MCP 확장 프로그램으로 설치

클라이언트별 기능 및 문제 해결에 대해서는 MCP 클라이언트의 문서를 참조하세요. 빌드된 dist/main-stdio.js을 직접 가리키는 구성에 대해서는 Claude Desktop에 연결도 참조하세요.

HTTP (로컬 웹 기반 AI)

HTTP 모드는 서버를 MCP 스트리밍 가능 HTTP 프로토콜을 사용하는 로컬 웹 서버로 실행합니다. 이는 머신을 가리키는 웹 기반 AI 도구가 통신하는 전송 방식이며, 원격 옵션이 외부 세계에 노출하는 방식이기도 합니다. 자체적으로 HTTP 모드는 localhost에만 바인딩됩니다.

localhost를 넘어 바인딩하나요? --host 0.0.0.0을 전달하거나(또는 리버스 프록시/공개 도메인 뒤에서 실행하는 경우), 서버는 DNS 리바인딩 보호를 위해 기본적으로 루프백 Host 헤더만 허용합니다 — 클라이언트가 사용하는 호스트 이름으로 ALLOWED_HOSTS를 설정하세요. HTTP 모드 구성을 참조하세요.

설정 - 방법 중 하나를 선택하세요:

방법 1: npx 사용 (권장 - 설치 불필요)

# Quick start
npx @ankimcp/anki-mcp-server

# With custom options
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765

방법 2: 글로벌 설치 사용

# Install once
npm install -g @ankimcp/anki-mcp-server

# Run the server
ankimcp

# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765

방법 3: 소스에서 설치 (개발용)

npm install
npm run build
npm run start:prod:http

로컬 HTTP 서버를 클라우드 호스팅 AI에서 접근 가능하게 만들려면 아래 원격 옵션 중 하나를 사용하세요.

원격

호스팅/원격 AI(예: 클라우드에서 실행되는 ChatGPT 또는 Claude.ai)는 localhost에 직접 접근할 수 없습니다. 이 옵션들은 원격 어시스턴트가 통신할 수 있도록 로컬 Anki를 인터넷에 노출합니다.

터널 (✅ 권장)

권장 원격 경로 — 인증 및 보안 적용. 원시 공개 포트와 달리 터널 모드는 로그인(OAuth 2.0 장치 흐름)이 필요하므로, URL을 추측한 누구에게나 엔드포인트가 열려 있지 않습니다.

터널 모드를 사용하면 자체 터널을 실행하지 않고도 웹 기반 AI 어시스턴트가 로컬 Anki에 접근할 수 있습니다. 서버는 WebSocket을 통해 관리형 AnkiMCP 터널 서비스(wss://tunnel.ankimcp.ai)에 연결하고 공개 URL을 할당받습니다. 인증이 내장되어 있어 ngrok 계정이나 별도의 터널 프로세스가 필요 없으며, 한 번만 로그인하면 됩니다.

로그인 (OAuth 장치 흐름):

터널 모드는 OAuth 2.0 장치 인증 권한 부여를 사용합니다. 로그인하면 URL에 코드가 이미 포함된 승인 페이지가 브라우저에서 자동으로 열리므로 입력할 필요 없이 승인만 하면 됩니다. (브라우저를 열 수 없는 경우, 터미널에 수동 입력용 확인 URL과 코드가 대체 수단으로 출력됩니다.) 성공하면 자격 증명이 ~/.ankimcp/credentials.json에 저장됩니다(파일 권한 0600).

# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
ankimcp --login
npx @ankimcp/anki-mcp-server --login

# Clear saved credentials
ankimcp --logout

터널 시작:

# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
ankimcp --tunnel
npx @ankimcp/anki-mcp-server --tunnel

# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
ankimcp --tunnel wss://my-tunnel.example.com

자격 증명이 없으면 --tunnel이 자동으로 로그인 흐름을 먼저 시작한 다음 터널을 계속 진행합니다. 이 자동 로그인에는 대화형 터미널이 필요합니다. stdout이 TTY가 아닌 경우(systemd, 헤드리스 Docker, CI) 서버가 빠르게 실패하고 먼저 ankimcp --login을 실행하도록 요청합니다. 연결되면 공개 터널 URL이 출력되며, Ctrl+C를 눌러 연결을 해제할 수 있습니다. 이 URL을 AI 어시스턴트와 공유하세요.

터널 모드 환경 변수:

변수설명기본값
TUNNEL_SERVER_URL터널 서버 WebSocket URL (--tunnel/--login 플래그 값이 이를 재정의함)wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_ID장치 흐름용 OAuth 클라이언트 ID. 고급 설정 — 자체 호스팅 터널/인증 서비스를 가리킬 때만 필요합니다.(내장)

장치 흐름 인증 엔드포인트(/auth/device, /auth/token)는 TUNNEL_SERVER_URL에서 파생되므로, --tunnel(또는 TUNNEL_SERVER_URL)을 다른 호스트로 지정하면 인증도 해당 호스트로 이동합니다.

작동 방식: 터널 모드는 인메모리 전송 뒤에서 MCP 서버를 프로세스 내에서 실행합니다(McpModule는 내장 전송 없이 시작됨). TunnelMcpService은 이 인메모리 전송을 MCP 서버에 연결하고, TunnelClient은 WebSocket을 통해 원격 터널 서비스로 브리징하여 MCP 요청을 중계하고 응답을 내보냅니다. AnkiConnect는 여전히 로컬 머신에서만 접근됩니다.

ngrok (비인증 대안)

관리형 터널 계정 없이 로컬 HTTP 모드를 공개적으로 노출하려면, 내장 --ngrok 플래그가 ngrok 하위 프로세스(src/services/ngrok.service.ts)를 시작하고 시작 배너에 공개 URL을 출력합니다.

# One-time ngrok setup, then:
ankimcp --ngrok

이 경로는 인증되지 않으므로 URL을 아는 사람은 누구나 Anki에 접근할 수 있어 터널보다 덜 안전합니다. 자체 ngrok 엔드포인트를 관리해야 할 특별한 이유가 없다면 터널을 선호하세요. (전역 ngrok 설치 및 인증 토큰 필요)

--ngrok 플래그는 --host-header=rewrite로 ngrok을 시작하므로, ngrok은 전달하기 전에 업스트림 Host을 localhost로 다시 작성합니다. 이렇게 하면 공개 *.ngrok 도메인을 ALLOWED_HOSTS에 추가하지 않고도 요청을 루프백 호스트 허용 목록 내에 유지합니다(DNS 리바인딩 보호 참조). 대신 수동으로 ngrok을 실행하는 경우 동일한 플래그(ngrok http --host-header=rewrite 3000)를 사용하세요. 그렇지 않으면 ngrok이 공개 ngrok 호스트 이름을 Host로 전달하고 서버가 403와 함께 거부합니다.

CLI 옵션 (모든 모드)

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -p, --port <port>              Port to listen on (HTTP mode, default: 3000)
  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks all write operations)
  --help                         Show help message

Usage with npx (no installation needed):
  npx @ankimcp/anki-mcp-server                        # HTTP mode
  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
  npx @ankimcp/anki-mcp-server --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

Usage with global installation:
  npm install -g @ankimcp/anki-mcp-server             # Install once
  ankimcp                                             # HTTP mode
  ankimcp --port 8080                                 # Custom port
  ankimcp --stdio                                     # STDIO mode
  ankimcp --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

읽기 전용 모드 (모든 모드)

--read-only 플래그는 Anki 컬렉션에 대한 모든 수정을 방지합니다. 활성화된 경우:

  • 모든 읽기 작업이 정상적으로 작동합니다(덱 탐색, 카드 보기, 노트 검색)
  • 복습 작업이 허용됩니다(동기화, answerCards, 일시 중지/일시 중지 해제)
  • 콘텐츠 수정이 차단됩니다(addNote, deleteNotes, createDeck, updateNoteFields 등)
  • 실수로 변경할 위험 없이 Anki 데이터를 안전하게 탐색하는 데 유용합니다.
# HTTP mode with read-only
ankimcp --read-only

# STDIO mode with read-only
ankimcp --stdio --read-only

# Can combine with other flags
ankimcp --ngrok --read-only

환경 변수를 통해 읽기 전용 모드를 활성화할 수도 있습니다:

READ_ONLY=true ankimcp

또는 MCP 클라이언트 구성에서:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Claude Desktop에 연결 (로컬 모드)

다음 방법 중 하나로 Claude Desktop에서 서버를 구성할 수 있습니다:

  • 설정 → 개발자 → 구성 편집으로 이동
  • 또는 구성 파일을 수동으로 편집

구성

Claude Desktop 구성에 다음을 추가하세요:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

/path/to/anki-mcp-server를 실제 프로젝트 경로로 바꾸세요.

구성 파일 위치

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

자세한 내용은 공식 MCP 문서를 참조하세요.

환경 변수 (선택 사항)

변수설명기본값
ANKI_CONNECT_URLAnkiConnect URLhttp://localhost:8765
ANKI_CONNECT_API_VERSIONAPI 버전6
ANKI_CONNECT_API_KEYAnkiConnect에 구성된 경우 API 키-
ANKI_CONNECT_TIMEOUT요청 시간 초과(ms)5000
READ_ONLY읽기 전용 모드 활성화 (true 또는 1)false
ALLOWED_HOSTSHTTP 모드: 루프백 외에 허용할 추가 Host 헤더 값 (쉼표로 구분된 호스트 이름). LAN/공개 주소에 바인딩하거나 리버스 프록시 뒤에서 실행할 때 필요합니다. HTTP 모드 구성을 참조하세요.루프백만
ALLOWED_ORIGINSHTTP 모드: 브라우저 Origin/Referer 패턴의 쉼표로 구분된 허용 목록 (와일드카드 지원, 예: https://*.ngrok.io).http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URL터널 서버 WebSocket URL (터널 모드 전용)wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPES파일 경로 가져오기에 허용할 추가 MIME 유형 (쉼표로 구분, 예: application/pdf)-
MEDIA_IMPORT_DIR파일 경로 가져오기를 이 디렉터리로 제한-
MEDIA_ALLOWED_HOSTSURL 가져오기에 대해 특정 사설 네트워크 호스트 허용 (쉼표로 구분, 예: 192.168.1.50,my-nas)-

사용 예시

노트 검색 및 업데이트

# Search for notes in a specific deck
findNotes(query: "deck:Spanish")

# Get detailed information about notes
notesInfo(notes: [1234567890, 1234567891])

# Update a note's fields (HTML content supported)
updateNoteFields(note: {
  id: 1234567890,
  fields: {
    "Front": "<b>¿Cómo estás?</b>",
    "Back": "How are you?"
  }
})

# Delete notes (requires confirmation)
deleteNotes(notes: [1234567890], confirmDeletion: true)

Anki 쿼리 구문 예시

findNotes 도구는 Anki의 강력한 쿼리 구문을 지원합니다:

  • "deck:DeckName" - 특정 덱의 모든 노트
  • "tag:important" - "important" 태그가 있는 노트
  • "is:due" - 복습 예정인 카드
  • "is:new" - 학습되지 않은 새 카드
  • "added:7" - 지난 7일 동안 추가된 노트
  • "front:hello" - 앞면 필드에 "hello"가 포함된 노트
  • "flag:1" - 빨간색 플래그가 있는 노트
  • "prop:due<=2" - 2일 이내에 예정된 카드
  • "deck:Spanish tag:verb" - 동사 태그가 있는 스페인어 덱 노트 (AND)
  • "deck:Spanish OR deck:French" - 두 덱 중 하나의 노트

중요 참고 사항

CSS 및 HTML 처리

  • notesInfo 도구는 적절한 렌더링 인식을 위해 CSS 스타일 정보를 반환합니다.
  • updateNoteFields 도구는 필드의 HTML 콘텐츠를 지원하고 CSS 스타일을 보존합니다.
  • 각 노트 모델에는 고유한 CSS 스타일이 있습니다. 모델별 CSS를 가져오려면 modelStyling을 사용하세요.

업데이트 경고

⚠️ 중요: updateNoteFields을(를) 사용할 때 업데이트 중에 Anki 브라우저에서 노트를 보지 마십시오. 그렇지 않으면 필드가 제대로 업데이트되지 않습니다. 업데이트하기 전에 브라우저를 닫거나 다른 노트로 전환하세요. 자세한 내용은 알려진 문제를 참조하세요.

삭제 안전성

deleteNotes 도구는 실수로 삭제하는 것을 방지하기 위해 명시적 확인(confirmDeletion: true)이 필요합니다. 노트를 삭제하면 관련된 모든 카드가 영구적으로 제거됩니다.

보안

미디어 파일 경로 및 URL 유효성 검사

미디어 도구(storeMediaFile, retrieveMediaFile, deleteMediaFile) 및 updateNoteFields 오디오/사진 필드에는 프롬프트 인젝션을 통한 오용을 방지하기 위한 보안 유효성 검사가 포함됩니다:

  • 파일 경로 가져오기는 미디어 파일 유형(이미지, 오디오, 비디오)으로만 제한됩니다. 비미디어 파일(예: SSH 키, 자격 증명, 셸 구성)은 MIME 유형에 따라 거부됩니다. 추가 파일 유형을 허용하려면 MEDIA_ALLOWED_TYPES을(를) 구성하거나, 특정 디렉터리로 가져오기를 제한하려면 MEDIA_IMPORT_DIR을(를) 구성하세요.
  • URL 가져오기는 SSRF 공격에 대해 유효성이 검사됩니다. 사설 네트워크(10.x, 172.16.x, 192.168.x), 루프백(127.x), 링크-로컬(169.254.x) 및 비 HTTP(S) 스킴에 대한 요청이 차단됩니다. 특정 사설 네트워크 호스트를 허용하려면 MEDIA_ALLOWED_HOSTS을(를) 구성하세요.
  • 파일 이름은 경로 탐색을 방지하기 위해 정리됩니다(예: ../../ 시퀀스가 제거됨).

이러한 보호는 storeMediaFile, retrieveMediaFile, deleteMediaFile 및 updateNoteFields 오디오/사진 필드에 적용됩니다.

Hideaki Takahashi님이 경로 탐색 취약점을 보고했습니다.

DNS 리바인딩 보호 (HTTP 전송)

HTTP 모드에서 실행할 때 서버는 모든 요청에서 Host 헤더의 유효성을 검사합니다. 기본적으로 포트에 관계없이 루프백 호스트(localhost, 127.0.0.1, ::1)만 허용됩니다. Host은(는) 브라우저에서 금지된 헤더이므로 악의적인 웹 페이지가 이를 위조할 수 없습니다. 이로 인해 리바운드 페이지가 스푸핑된 Host과(와) Origin 없이 로컬 서버에 도달하여 MCP 도구에 접근하는 DNS 리바인딩 경로가 차단됩니다. 허용되지 않은 Host은(는) 403과(와) 함께 거부됩니다.

0.0.0.0에 바인딩하거나, 리버스 프록시 뒤에서 실행하거나, 공개 터널 도메인을 노출하는 경우, 해당 호스트를 허용하도록 ALLOWED_HOSTS(쉼표로 구분된 호스트 이름)을 설정하세요. ngrok으로 터널링할 때 서버는 --host-header=rewrite을(를) 사용하므로 업스트림은 여전히 루프백 Host을(를) 보게 됩니다. 전체 옵션 목록은 HTTP 모드 구성을 참조하세요.

avishaigo-commits님과 yotampe-pluto님이 DNS 리바인딩 취약점을 보고했습니다.

개인정보 처리방침

이 MCP 서버는 사용자의 머신에서 로컬로 실행되며 원격 측정, 분석 또는 사용 데이터를 수집하지 않습니다.

전체 정책: https://ankimcp.ai/privacy/

  • 데이터 수집: 서버는 어떤 것도 수집하지 않습니다. AI 어시스턴트와 로컬 AnkiConnect 플러그인 간의 요청을 프록시합니다.
  • 사용 / 저장: 서버 측 저장소가 없습니다. 모든 플래시카드 데이터는 사용자 기기의 Anki 설치본에 남아 있습니다.
  • 제3자 공유: 없음. 서버는 사용자가 구성한 AnkiConnect URL(기본값: localhost)하고만 통신합니다. Anki의 내장 AnkiWeb 동기화를 활성화하면, 이는 Anki 설치본과 AnkiWeb 간에 직접 이루어지며 이 서버의 범위를 벗어납니다.
  • 보존: 해당 없음 — 서버 측에 데이터가 보존되지 않습니다.
  • 문의: support@ankimcp.ai

알려진 문제

알려진 문제 및 제한 사항의 포괄적인 목록은 문서를 참조하세요:

알려진 문제 문서

중대한 제한 사항

브라우저에서 볼 때 노트 업데이트 실패

⚠️ 중요: updateNoteFields을(를) 사용하여 노트를 업데이트할 때, 현재 Anki 브라우저 창에서 해당 노트를 보고 있으면 업데이트가 자동으로 실패합니다. 이는 업스트림 AnkiConnect 제한 사항입니다.

해결 방법: 업데이트하기 전에 항상 브라우저를 닫거나 다른 노트로 이동하세요.

자세한 내용 및 기타 알려진 문제는 전체 문서를 참조하세요.

문제 해결

ERR_REQUIRE_ESM 오류

다음과 같은 오류가 표시되는 경우:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

이는 Node.js 버전이 지원되지 않음을 의미합니다. 서버에는 Node.js 22.12.0 이상이 필요합니다.

참고: 지원되는 최소 런타임은 Node.js 22.12.0입니다. Node.js 20 (Iron)은 2026-04-30에 수명이 종료되어 더 이상 지원되지 않습니다.

버전 확인:

node --version

해결책: Node.js를 버전 22.12.0 이상으로 업데이트하세요. nodejs.org에서 다운로드하거나 nvm과 같은 버전 관리자를 사용할 수 있습니다.

개발

전송 모드

이 서버는 별도의 진입점을 통해 세 가지 MCP 전송 모드를 지원합니다:

STDIO 모드 (기본값)

  • Claude Desktop과 같은 로컬 MCP 클라이언트용
  • 통신에 표준 입출력 사용
  • 진입점: dist/main-stdio.js
  • 실행: npm run start:prod:stdio 또는 node dist/main-stdio.js
  • MCPB 번들: STDIO 모드 사용

HTTP 모드 (스트리밍 가능 HTTP)

  • 원격 MCP 클라이언트 및 웹 기반 통합용
  • MCP 스트리밍 가능 HTTP 프로토콜 사용
  • 진입점: dist/main-http.js
  • 실행: npm run start:prod:http 또는 node dist/main-http.js
  • 기본 포트: 3000 (PORT 환경 변수로 설정 가능)
  • 기본 호스트: 127.0.0.1 (HOST 환경 변수로 설정 가능)
  • MCP 엔드포인트: http://127.0.0.1:3000/ (루트 경로)

터널 모드 (관리형 WebSocket 터널)

  • 내장 인증 기능이 있는 관리형 AnkiMCP 터널 서비스를 통한 웹 기반 AI 어시스턴트용
  • MCP 서버는 인메모리 전송 뒤에서 프로세스 내에서 실행되며, TunnelMcpService이 이를 MCP 서버에 연결하고 TunnelClient이 WebSocket을 통해 터널 서비스로 브리징합니다.
  • 진입점: dist/main-tunnel.js
  • 실행: node dist/main-tunnel.js --tunnel (또는 ankimcp --tunnel)
  • 인증: ankimcp --login / ankimcp --logout; 자격 증명은 ~/.ankimcp/credentials.json (0600)에 저장됨
  • 개발: npm run start:dev:tunnel (감시 모드, --tunnel --debug 실행)

빌드

npm run build  # Builds once, creates dist/ with all three entry points

main-stdio.js, main-http.js, main-tunnel.js는 모두 동일한 dist/ 디렉터리에 빌드됩니다. 필요에 따라 실행할 것을 선택하세요.

HTTP 모드 구성

환경 변수:

  • PORT - HTTP 서버 포트 (기본값: 3000)
  • HOST - 바인드 주소 (기본값: 로컬호스트 전용 127.0.0.1)
  • ALLOWED_HOSTS - 내장 루프백 세트(localhost, 127.0.0.1, ::1) 외에 허용할 추가 Host 헤더 값의 쉼표로 구분된 목록. 호스트 이름만, 포트 무관. 기본값: 루프백만.
  • ALLOWED_ORIGINS - 브라우저 Origin/Referer 패턴의 쉼표로 구분된 허용 목록; 와일드카드 지원 (예: https://*.ngrok.io). 기본값: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
  • LOG_LEVEL - 로깅 레벨 (기본값: info)

보안:

  • Host 헤더 유효성 검사 (DNS 리바인딩 보호) — 모든 HTTP 요청은 허용 목록과 일치하는 Host 헤더를 포함해야 합니다. 기본적으로 포트에 관계없이 루프백 호스트(localhost, 127.0.0.1, ::1)만 허용됩니다. Host은 브라우저에서 금지된 헤더이므로 악의적인 웹 페이지가 이를 위조할 수 없습니다. 이는 리바운드 페이지가 스푸핑된 Host와 Origin 없이 서버에 도달하는 DNS 리바인딩 경로를 차단합니다. 허용되지 않은 Host은 403로 거부됩니다.
  • Origin 헤더 유효성 검사 — 존재하지만 허용되지 않은 Origin/Referer가 있는 브라우저 요청은 거부됩니다. Origin가 없는 요청(curl, Postman, MCP-over-HTTP 클라이언트)은 허용됩니다. Host 유효성 검사가 리바인딩에 대한 방어 수단입니다.
  • 기본적으로 로컬호스트(127.0.0.1)에 바인딩됩니다.
  • 현재 버전에서는 인증이 없습니다 (OAuth 지원 예정).

HTTP 모드를 로컬호스트 외부에 노출 — LAN/공용 주소에 바인딩하거나 리버스 프록시 또는 공용 도메인 뒤에 서버를 배치하는 경우, 클라이언트가 사용할 호스트 이름으로 ALLOWED_HOSTS을 반드시 설정해야 합니다. 그렇지 않으면 모든 비루프백 요청이 403로 거부됩니다:

# Bind to all interfaces and accept the machine's LAN name + a public domain
ALLOWED_HOSTS=my-nas.local,anki.example.com PORT=8080 HOST=0.0.0.0 node dist/main-http.js

ALLOWED_HOSTS 없이 0.0.0.0/::에 바인딩하면 서버는 루프백 Host 헤더만 허용된다는 시작 경고를 기록합니다.

Docker / 리버스 프록시 / 공용 도메인: 동일한 규칙이 적용됩니다. Docker에서는 일반적으로 요청이 컨테이너의 게시된 호스트 이름 또는 프록시의 Host와 함께 도착하므로 그에 따라 ALLOWED_HOSTS을 설정하세요. 리버스 프록시(nginx, Caddy, Traefik)는 원본 Host를 전달하고 해당 호스트 이름을 ALLOWED_HOSTS에 나열하거나, 업스트림 Host을 localhost로 다시 작성해야 합니다. 내장된 --ngrok 통합은 이를 자동으로 처리합니다(아래 참조).

예시: 모드 실행

# Development - STDIO mode (watch mode with auto-rebuild)
npm run start:dev:stdio

# Development - HTTP mode (watch mode with auto-rebuild)
npm run start:dev:http

# Production - STDIO mode
npm run start:prod:stdio
# or
node dist/main-stdio.js

# Production - HTTP mode
npm run start:prod:http
# or
PORT=8080 HOST=0.0.0.0 node dist/main-http.js

MCPB 번들 빌드

배포 가능한 MCPB 번들을 생성하려면:

npm run mcpb:bundle

이 명령은 다음을 수행합니다:

  1. package.json에서 manifest.json로 버전 동기화
  2. 이전 .mcpb 파일 제거
  3. TypeScript 프로젝트 빌드
  4. dist/ 및 node_modules/을 .mcpb 파일로 패키징
  5. mcpb clean를 실행하여 devDependencies 제거 (번들 크기를 ~47MB에서 ~10MB로 최적화)

출력 파일 이름은 anki-mcp-server-X.X.X.mcpb이며 원클릭 설치용으로 배포할 수 있습니다.

번들에 포함되는 항목

MCPB 번들에는 다음이 포함됩니다:

  • 컴파일된 JavaScript (dist/ 디렉터리 - 세 가지 진입점 모두 포함)
  • 프로덕션 종속성만 (node_modules/ - mcpb clean에 의해 devDependencies 제거됨)
  • 패키지 메타데이터 (package.json)
  • 매니페스트 구성 (manifest.json - main-stdio.js를 사용하도록 구성됨)
  • 아이콘 (icon.png)

소스 파일, 테스트, 개발 구성은 .mcpbignore를 통해 자동으로 제외됩니다.

Claude Desktop에서의 로깅

Claude Desktop에서 MCPB 확장으로 실행할 때 로그는 다음 위치에 기록됩니다:

로그 위치: ~/Library/Logs/Claude/ (macOS)

로그는 여러 파일로 분할됩니다:

  • main.log - 일반 Claude Desktop 애플리케이션 로그
  • mcp-server-Anki MCP Server.log - 이 확장에 대한 MCP 프로토콜 메시지
  • mcp.log - 모든 서버의 결합된 MCP 로그

참고: pino 로거 출력(서버 코드의 INFO, ERROR, WARN 메시지)은 stderr로 전송되며 MCP 관련 로그 파일에 나타납니다. Claude Desktop이 어떤 로그 파일이 어떤 메시지를 받을지 결정하지만, 일반적으로:

  • 애플리케이션 시작 및 MCP 프로토콜 통신 → MCP 관련 로그
  • 서버 내부 로깅(pino) → MCP 관련 로그 및 때로는 main.log

실시간으로 로그를 보려면:

tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log

MCP 서버 디버깅

MCP Inspector를 사용하고 IDE(WebStorm, VS Code 등)에서 디버거를 연결하여 MCP 서버를 디버깅할 수 있습니다.

HTTP 모드 참고: MCP Inspector로 HTTP 모드(스트리밍 가능 HTTP)를 테스트할 때 CORS 오류를 방지하려면 "Connection Type: Via Proxy"를 사용하세요.

1단계: MCP Inspector에서 디버그 서버 구성

mcp-inspector-config.json에는 이미 디버그 서버 구성이 포함되어 있습니다:

{
  "mcpServers": {
    "stdio-server-debug": {
      "type": "stdio",
      "command": "node",
      "args": ["--inspect-brk=9229", "dist/main-stdio.js"],
      "env": {
        "MCP_SERVER_NAME": "anki-mcp-stdio-debug",
        "MCP_SERVER_VERSION": "1.0.0",
        "LOG_LEVEL": "debug"
      },
      "note": "Anki MCP server with debugging enabled on port 9229"
    }
  }
}

2단계: 디버그 서버 시작

디버그 서버와 함께 MCP Inspector를 실행합니다:

npm run inspector:debug

이렇게 하면 포트 9229에서 Node.js 디버깅이 활성화된 상태로 서버가 시작되고 첫 번째 줄에서 실행이 일시 중지됩니다.

3단계: IDE에서 디버거 연결

WebStorm
  1. Run → Edit Configurations로 이동
  2. 새 Attach to Node.js/Chrome 구성 추가
  3. 포트를 9229로 설정
  4. Debug를 클릭하여 연결
VS Code
  1. 디버그 패널 열기 (Ctrl+Shift+D / Cmd+Shift+D)
  2. Debug MCP Server (Attach) 구성 선택
  3. F5를 눌러 연결

4단계: 중단점 설정 및 디버깅

연결되면 다음을 수행할 수 있습니다:

  • TypeScript 소스 파일에 중단점 설정
  • 코드 실행 단계별 진행
  • 변수 및 호출 스택 검사
  • 디버그 콘솔을 사용하여 표현식 평가

디버거는 소스 맵과 함께 작동하므로 컴파일된 JavaScript 대신 원본 TypeScript 코드를 디버깅할 수 있습니다.

Claude Desktop으로 디버깅

Node.js 디버거를 활성화하고 IDE를 연결하여 Claude Desktop 내에서 실행되는 동안 MCP 서버를 디버깅할 수도 있습니다.

1단계: 디버깅을 위한 Claude Desktop 구성

Claude Desktop 구성을 업데이트하여 디버깅을 활성화합니다:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": [
        "--inspect=9229",
        "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
      ],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

주요 변경 사항: dist/main-stdio.js 경로 앞에 --inspect=9229 추가

디버그 옵션:

  • --inspect=9229 - 디버거를 즉시 시작하고 차단하지 않음 (권장)
  • --inspect-brk=9229 - 디버거가 연결될 때까지 실행 일시 중지 (시작 문제 디버깅용)

2단계: Claude Desktop 다시 시작

구성을 저장한 후 Claude Desktop을 다시 시작합니다. 이제 MCP 서버가 포트 9229에서 디버깅이 활성화된 상태로 실행됩니다.

3단계: IDE에서 디버거 연결

WebStorm
  1. Run → Edit Configurations로 이동
  2. + 버튼을 클릭하고 Attach to Node.js/Chrome 선택
  3. 구성:
    • Name: Attach to Anki MCP (Claude Desktop)
    • Host: localhost
    • Port: 9229
    • Attach to: Node.js < 8 또는 Chrome or Node.js > 6.3 (WebStorm 버전에 따라 다름)
  4. OK 클릭
  5. Debug (Shift+F9)를 클릭하여 연결
VS Code
  1. .vscode/launch.json에 추가:
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Anki MCP (Claude Desktop)",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}
  1. 디버그 패널 열기 (Ctrl+Shift+D / Cmd+Shift+D)
  2. Attach to Anki MCP (Claude Desktop) 선택
  3. F5를 눌러 연결

4단계: 실시간 디버깅

연결되면 다음을 수행할 수 있습니다:

  • TypeScript 소스 파일(예: src/mcp/primitives/essential/tools/create-model.tool.ts)에 중단점 설정
  • Claude Desktop을 정상적으로 사용 - 도구가 호출될 때 중단점이 적중됨
  • 코드 실행 단계별 진행
  • 변수 및 호출 스택 검사
  • 디버그 콘솔 사용

예시: create-model.tool.ts의 119번째 줄에 중단점을 설정한 다음 Claude에게 새 모델을 만들도록 요청합니다. 디버거가 중단점에서 일시 중지됩니다!

참고: 디버거는 Claude Desktop이 실행되는 동안 계속 연결되어 있습니다. Claude Desktop을 다시 시작하지 않고도 언제든지 분리/재연결할 수 있습니다.

빌드 명령

npm run build              # Build the project (compile TypeScript to JavaScript)
npm run start:dev:stdio    # STDIO mode with watch (auto-rebuild)
npm run start:dev:http     # HTTP mode with watch (auto-rebuild)
npm run type-check         # Run TypeScript type checking
npm run lint               # Run ESLint
npm run mcpb:bundle        # Sync version, clean, build, and create MCPB bundle

NPM 패키지 테스트 (로컬)

게시하기 전에 로컬에서 npm 패키지를 테스트합니다:

# 1. Create local package
npm run pack:local         # Builds and creates @ankimcp/anki-mcp-server-*.tgz

# 2. Install globally from local package
npm run install:local      # Installs from ./@ankimcp/anki-mcp-server-*.tgz

# 3. Test the command
ankimcp                    # Runs HTTP server on port 3000

# 4. Uninstall when done testing
npm run uninstall:local    # Removes global installation

작동 방식:

  • npm pack은 npm publish가 생성하는 것과 동일한 .tgz 파일을 생성합니다.
  • .tgz에서 설치하면 사용자가 npm install -g ankimcp에서 얻는 것을 시뮬레이션합니다.
  • 이를 통해 npm에 게시하기 전에 전체 사용자 경험을 테스트할 수 있습니다.

테스트 명령

npm test              # Run all tests
npm run test:unit     # Run unit tests only
npm run test:tools    # Run tool-specific tests
npm run test:workflows # Run workflow integration tests
npm run test:e2e      # Run end-to-end tests
npm run test:cov      # Run tests with coverage report
npm run test:watch    # Run tests in watch mode
npm run test:debug    # Run tests with debugger
npm run test:ci       # Run tests for CI (silent, with coverage)

테스트 커버리지

이 프로젝트는 다음에 대해 70% 최소 커버리지 임계값을 유지합니다:

  • 분기
  • 함수
  • 라인
  • 구문

커버리지 보고서는 coverage/ 디렉터리에 생성됩니다.

버전 관리

이 프로젝트는 1.0 이전 개발 접근 방식으로 시맨틱 버전 관리를 따릅니다:

  • 0.x.x - 베타/개발 버전 (현재 단계)

    • 0.1.x - 버그 수정 및 패치
    • 0.2.0+ - 새로운 기능 또는 사소한 개선
    • 주요 변경 사항은 0.x 버전에서 허용됩니다.

  • 1.0.0 - 첫 번째 안정 릴리스

    • API가 안정적이고 테스트되었을 때 릴리스됩니다.
    • 주요 변경 사항은 주 버전 증가(2.0.0 등)가 필요합니다.

현재 상태: 0.22.0 - 활발한 베타 개발 중. 최근 기능으로는 컬렉션 전체 복습 분석(deck이 생략되면 review_stats가 이제 모든 덱에 걸쳐 집계됨), 모델 필드 관리(addModelField, removeModelField, renameModelField, repositionModelField), 배치 노트 생성(addNotes), 통합 ngrok 터널링(--ngrok 플래그), 미디어 파일 관리, 모델/템플릿 관리, 포괄적인 덱 통계가 포함됩니다. API는 피드백과 테스트에 따라 변경될 수 있습니다.

MCPB 사양 발전

이 프로젝트는 아직 발전 중인 Anthropic의 MCPB 번들 사양을 대상으로 합니다. https://github.com/modelcontextprotocol/mcpb에서 사양을 추적하며, 준수를 위해 주요 변경 사항을 도입할 수 있습니다. 주요 변경 사항은 0.x.x 버전 관리 체계에서 허용됩니다.

유사 프로젝트

Anki MCP 통합을 탐색 중이라면 이 분야의 다른 프로젝트는 다음과 같습니다:

scorzeth/anki-mcp-server

  • 상태: 중단된 것으로 보임 (최근 업데이트 없음)
  • Anki MCP 통합의 초기 구현

nailuoGG/anki-mcp-server

  • 접근 방식: 경량, 단일 파일 구현
  • 아키텍처: 모든 도구가 하나의 파일에 있는 절차적 코드 구조
  • 적합한 용도: 간단한 사용 사례, 최소한의 종속성 이 프로젝트가 다른 이유:
  • 엔터프라이즈급 아키텍처: NestJS 기반으로 의존성 주입 활용
  • 모듈식 설계: 각 도구가 별도의 클래스로 구성되어 관심사가 명확히 분리됨
  • 유지보수성: 기존 코드를 건드리지 않고 새로운 기능을 쉽게 확장 가능
  • 테스트: 70% 커버리지 요구사항을 갖춘 포괄적인 테스트 스위트
  • 타입 안전성: Zod 검증을 통한 엄격한 TypeScript
  • 오류 처리: 유용한 사용자 피드백을 제공하는 견고한 오류 처리
  • 프로덕션 준비 완료: 적절한 로깅, 진행 상황 보고, MCPB 번들 지원
  • 확장성: 기본 도구에서 복잡한 워크플로우로 쉽게 성장 가능

사용 사례: 고급 Anki 통합을 구축하기 위한 견고한 기반이 필요하거나 기능을 크게 확장할 계획이라면, 이 프로젝트의 아키텍처 접근 방식은 시간이 지남에 따라 유지보수와 확장을 더 쉽게 만들어 줍니다.

유용한 링크

라이선스 및 저작자 표시

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 전체 내용은 LICENSE를 참조하십시오.

Copyright © 2026 Anatoly Tarnavsky.

제3자 저작자 표시

  • **Anki®**는 Ankitects Pty Ltd의 등록 상표입니다. 이 프로젝트는 비공식 제3자 도구이며 Ankitects Pty Ltd와 제휴, 보증 또는 후원 관계가 없습니다. Anki 로고는 https://apps.ankiweb.net 링크와 함께 Anki를 참조하기 위한 대체 라이선스에 따라 사용됩니다. 공식 Anki 애플리케이션은 https://apps.ankiweb.net을 방문하십시오.

  • 모델 컨텍스트 프로토콜 (MCP) 은 Anthropic의 개방형 표준입니다. MCP 로고는 공식 MCP 문서 저장소에서 가져온 것이며 MIT 라이선스에 따라 사용됩니다. MCP에 대한 자세한 내용은 https://modelcontextprotocol.io를 방문하십시오.

  • 이것은 Anki와 MCP 기술을 연결하는 독립적인 프로젝트입니다. 모든 상표, 서비스 마크, 상호, 제품명 및 로고는 해당 소유자의 자산입니다.