Anki MCP

공식

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

GitHub
482
이 MCP 사용해 보기스폰서

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

  • 복습 카드 대화형으로 검토하기 — 어시스턴트에게 get_due_cards로 복습할 카드를 불러오고, present_card로 각 카드를 제시한 뒤, rate_card로 평가를 기록하도록 요청하세요.
  • 플래시카드 생성 및 일괄 추가 — 어시스턴트가 addNotes로 노트를 대량 생성하게 하고, 필요 시 createModel과 updateModelStyling으로 맞춤 모델을 먼저 만들게 하세요.
  • 기존 노트 검색 및 편집 — Anki 쿼리 구문과 함께 findNotes를 사용하고, notesInfo로 세부 정보를 확인한 뒤, updateNoteFields로 필드를 업데이트하세요.
  • 덱 및 일정 관리 — createDeck로 덱을 만들고, changeDeck으로 카드를 이동하거나, setDueDate와 forgetCards로 카드 일정을 재조정하세요.
  • 노트에 미디어 가져오기 — 어시스턴트에게 storeMediaFile로 로컬 이미지나 URL을 업로드하고, 이를 노트의 필드에 삽입하도록 요청하세요.
  • Anki GUI 제어 — guiBrowse와 guiEditNote로 브라우저나 편집기를 열거나, guiSelectedNotes로 선택된 노트를 가져오세요.

문서

Anki MCP 서버

Tests npm version

Anki + MCP Integration

Anki를 Model Context Protocol을 통해 AI 어시스턴트와 원활하게 통합하세요

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

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

자연어 상호작용으로 Anki 경험을 변화시키세요 — 마치 개인 튜터가 있는 것처럼. AI 어시스턴트는 단순히 질문과 답변을 제시하는 것이 아니라, 개념을 설명하고, 학습 과정을 더 흥미롭고 인간적으로 만들며, 맥락을 제공하고, 학습 스타일에 적응할 수 있습니다. 즉석에서 노트를 생성하고 편집하여 학습 세션을 역동적인 대화로 바꿔줍니다. 더 많은 기능이 곧 제공될 예정입니다!

예시 및 튜토리얼

이 MCP 서버를 Claude Desktop과 함께 사용하는 방법에 대한 종합적인 가이드, 실제 예시, 단계별 튜토리얼은 다음을 참조하세요:

ankimcp.ai - 실용적인 예시와 사용 사례가 포함된 전체 문서

보충 문서는 docs/을 참조하세요. 리뷰어 설정 가이드와 샘플 Anki 덱이 포함되어 있습니다.

예시 사용 사례

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

  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).

사용 가능한 도구

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

필수 도구

복습 및 학습

  • sync - 최신 데이터를 가져오고 변경 사항을 푸시하기 위해 AnkiWeb과 동기화
  • get_due_cards - 복습할 카드 가져오기, 덱별 필터링 가능 (include_answer: true이 아닌 경우 답변 생략, 기본값 false)
  • get_cards - 상태(복습 예정, 새 카드, 학습 중, 일시 중단, 파묻힘)와 덱으로 유연하게 필터링하여 카드 가져오기 (include_answer: true이 아닌 경우 답변 생략, 기본값 false)
  • present_card - 질문/앞면과 함께 복습할 카드 표시
  • rate_card - 카드 성능 평가(Again, Hard, Good, Easy) 및 다음 복습 일정 예약
  • forgetCards - 복습을 기록하지 않고 카드를 새 카드로 재설정하여 일정 폐기
  • setDueDate - 복습을 기록하지 않고 카드를 N일 후에 복습 예정으로 재일정 ("0", "3-7", "1!")

참고: forgetCards와 setDueDate는 복습을 기록하지 않고 일정을 변경합니다. 이것이 rate_card와 구분되는 점입니다. 카드의 일정이 잘못된 경우 답변보다는 이 도구를 사용하세요: 카드를 Again로 평가하여 더 깊이 파묻으면 실제 실패가 기록되고 난이도 계수가 낮아져 향후 일정과 통계가 영구적으로 왜곡됩니다. forgetCards는 간격을 지우고 카드를 처음부터 다시 시작합니다; setDueDate는 카드의 기록을 유지하고 다음 복습만 이동합니다.

참고: 카드 front/back 콘텐츠는 Anki가 표시하는 방식대로 각 카드의 자체 템플릿에서 렌더링되므로, 뒤집힌 카드와 클로즈 카드가 올바른 방향으로 표시됩니다. 카드 템플릿에 추가된 정적 텍스트도 출력에 나타납니다.

덱 관리

  • listDecks - 모든 덱 나열, 선택적으로 덱별 학습 큐 통계 포함
  • deckStats - 단일 덱에 대한 종합 통계 가져오기 (학습 큐, 실제 카드 상태 수, 난이도/간격 분포)
  • createDeck - 새 빈 덱 생성 (Parent::Child 지원, 최대 2단계)
  • changeDeck - 카드를 다른 덱으로 이동 (없으면 생성)

참고: 덱 통계에는 두 가지 종류가 있습니다. counts 블록(및 listDecks가 보고하는 모든 것)은 Anki의 덱 브라우저를 반영합니다: 각 덱의 일일 새 카드/복습 한도에 의해 제한된 오늘 복습 예정 카드, 일시 중단 및 파묻힌 카드는 제외 — 따라서 review은 "성숙한 카드"가 아니며 other 버킷은 단순히 산술적 나머지입니다(대부분 오늘 복습 예정이 아닌 복습 카드와 일일 한도를 초과한 새 카드). 실제 상태별 합계는 deckStats / collection_stats의 states 블록을 사용하세요. 이는 Anki 검색을 통해 new, learning, review, suspended 및 buried를 계산하며, 복습 예정일과 일일 한도를 무시합니다.

노트 관리

  • 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에 있습니다.

소스에서 설치 (개발용)

개발 또는 고급 사용의 경우 (테스트 스위트 실행에는 Node.js 24.9+ 필요 — npm 테스트 스크립트는 require(esm)을 통해 ESM 전용 NestJS 12 패키지를 로드하며, Jest는 해당 버전에서만 지원합니다; 서버 사용을 위한 런타임 요구 사항은 22.12.0+로 유지):

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 Streamable 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)을 다른 호스트로 가리키면 인증도 해당 호스트로 이동합니다.

작동 방식: 터널 모드는 인메모리 전송(TunnelTransport) 뒤에서 MCP 서버를 프로세스 내에서 실행합니다. 해당 전송이 MCP 서버를 소유하고 각 중계 요청 본문을 응답으로 변환하며, TunnelClient이 WebSocket을 통해 원격 터널 서비스에 연결합니다 — MCP 요청을 보내고 응답을 받습니다. AnkiConnect는 여전히 로컬 컴퓨터에서만 접근됩니다.

프로토콜 개정: 터널이 MCP 서버를 프로세스 내에서 연결하므로 터널 모드는 2025 개정 MCP 프로토콜만 제공하는 반면, STDIO 및 HTTP 모드는 2025와 최신 2026-07-28 개정을 모두 제공합니다. 모든 도구는 어느 쪽이든 동일하게 작동합니다 — 그러나 2026-07-28만 사용하는 클라이언트는 터널을 통해 프로토콜 버전 오류로 거부됩니다. 해당 클라이언트에는 STDIO 또는 HTTP 모드를 실행하세요.

ngrok (인증되지 않은 대안)

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

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

이 경로는 인증되지 않습니다 — URL을 가진 사람은 누구나 사용자의 Anki에 접근할 수 있으므로 터널보다 덜 안전합니다. 특별한 이유가 없는 한 터널을 선호하세요. (전역 ngrok 설치 및 authtoken 필요.)

--ngrok 플래그는 --host-header=rewrite으로 ngrok을 시작하므로 ngrok은 전달 전에 업스트림 Host을 localhost으로 다시 작성합니다. 이렇게 하면 ALLOWED_HOSTS에 공개 *.ngrok 도메인을 추가하지 않고도 요청이 루프백 Host 허용 목록(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 <number>            Port to listen on (HTTP mode; default: 3000, or PORT env var)
  -h, --host <address>           Host to bind to (HTTP mode; default: 127.0.0.1, or HOST env var)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765, or ANKI_CONNECT_URL env var)
  --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, suspend/unsuspend)
  • 콘텐츠 수정이 차단됩니다 (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
PORTHTTP 모드: 수신 대기 포트 (--port 플래그가 우선)3000
HOSTHTTP 모드: 바인딩 주소 (--host 플래그가 우선)127.0.0.1
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는 브라우저에서 금지된 헤더이므로, 악성 웹 페이지는 이를 위조할 수 없습니다. 이는 DNS 리바인딩 경로를 차단합니다. 리바인딩된 페이지가 스푸핑된 Host와 Origin 없이 로컬 서버에 도달하여 MCP 도구에 접근하는 것을 방지합니다. 허용되지 않은 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 Streamable 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 서버는 인메모리 전송 뒤에서 프로세스 내에서 실행됩니다. TunnelTransport가 MCP 서버를 소유하고 TunnelClient가 WebSocket을 통해 터널 서비스에 연결합니다.
  • 프로토콜: 2025 MCP 개정판만 제공(STDIO 및 HTTP는 2026-07-28도 제공)
  • 진입점: 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 - 바인드 주소(기본값: localhost 전용 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)

보안:

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

HTTP 모드를 localhost 이상으로 노출 — 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

0.0.0.0/::에 ALLOWED_HOSTS 없이 바인딩하면 서버는 루프백 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 모드(Streamable 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% 커버리지 기준을 유지합니다:

  • 분기(Branches)
  • 함수(Functions)
  • 줄(Lines)
  • 문(Statements)

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

버전 관리

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

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

    • 0.1.x — 버그 수정 및 패치
    • 0.2.0+ — 새로운 기능 또는 사소한 개선
    • 0.x 버전에서는 호환성을 깨는 변경이 허용됩니다

  • 1.0.0 — 첫 번째 안정 버전

    • API가 안정적이고 테스트되었을 때 출시됩니다
    • 호환성을 깨는 변경은 주요 버전 업데이트(2.0.0 등)가 필요합니다

현재 상태: 0.22.0 — 활발한 베타 개발 중. 최근 기능에는 컬렉션 전체 리뷰 분석(review_stats이 이제 deck이 생략될 때 모든 덱을 집계), 모델 필드 관리(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.

타사 저작자 표시

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

  • **Model Context Protocol (MCP)**는 Anthropic의 오픈 표준입니다. MCP 로고는 공식 MCP 문서 저장소에서 가져왔으며 MIT 라이선스 하에 사용됩니다. MCP에 대한 자세한 내용은 https://modelcontextprotocol.io을 방문하세요.

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