ankimcp/anki-mcp-server

Anki MCP 서버 – 개요

Anki MCP 서버는 Model Context Protocol (MCP)을 구현한 Node‑JS 서비스입니다. AI 어시스턴트(Claude, Cursor, Cline, Zed 등)와 Anki 간격 반복 앱(AnkiConnect 플러그인을 통해) 사이에 위치합니다. 풍부한 '도구' 세트(데크 목록, 기한 지난 카드 가져오기, 노트 생성, 미디어 업로드, Anki 데스크톱 창을 구동하는 GUI 명령 등)를 노출함으로써 서버는 언어 모델이 마치 대화형 튜터처럼 개인 플래시카드 컬렉션과 대화할 수 있게 합니다.

존재 이유

• AI 기반 학습 – 채팅을 벗어나지 않고 어시스턴트에게 데크 검토, 새 카드 생성, 이미지 추가를 요청할 수 있습니다.
• 표준화된 전송 – MCP는 많은 AI 클라이언트 제품이 이미 이해하는 JSON‑over‑STDIO 또는 HTTP API를 정의합니다.
• Anki와 분리 – 서버는 Anki 외부에서 실행되므로 하위 프로세스를 시작하거나 로컬 웹 서버를 호출할 수 있는 모든 AI 클라이언트가 사용할 수 있습니다.

이 저장소와 애드온 사용 시기

• 가장 간단한 올인원 경험(HTTP, 원격 터널, Node.js 불필요)을 위해 AnkiMCP 애드온(Anki 내부에 설치)을 사용하세요.
• 다음이 필요할 때 이 독립 서버를 사용하세요:
  • STDIO 전송 – Claude Desktop, Cursor, Cline, Zed 등에서 필요.
  • MCPB 번들 – Claude Desktop용 원클릭 설치 프로그램.

---

핵심 기능(README에 명시된 대로)

카테고리	도구(선택)	기능
복습 및 학습	sync, get_due_cards, present_card, rate_card, forgetCards, setDueDate	AnkiWeb와 동기화, 복습 예정 카드 가져오기, 카드 표시, 평가 기록, 일정 수동 조정.
데크 관리	listDecks, deckStats, createDeck, changeDeck	데크 목록, 상세 통계, 새 데크 생성(2단계 계층 지원), 데크 간 카드 이동.
노트 관리	addNote, addNotes, findNotes, notesInfo, updateNoteFields, deleteNotes	단일 또는 일괄 노트 생성, Anki 쿼리 구문으로 검색, 노트 필드 읽기/편집, 노트 삭제.
태그 관리	getTags, addTags, removeTags, replaceTags, clearUnusedTags	태그 검색, 추가, 제거, 이름 변경, 정리.
미디어 관리	getMediaFilesNames, retrieveMediaFile, storeMediaFile, deleteMediaFile	미디어 파일 목록, 다운로드(base64), 업로드(경로, URL 또는 base64), 삭제. README는 속도를 위해 파일 경로 또는 URL 사용을 권장.
모델/템플릿 관리	modelNames, modelFieldNames, modelStyling, modelTemplates, createModel, updateModelStyling, addModelField …	노트 유형(모델), 필드, CSS 스타일, 카드 템플릿 검사, 생성, 수정.
통계	collection_stats, review_stats	전체 컬렉션 통계 및 복습 기록 분석.
GUI 도구(복습용 아님)	guiBrowse, guiAddCards, guiEditNote, guiDeckOverview, guiCurrentCard, guiUndo	Anki 데스크톱 창을 열거나 UI를 조작하는 명령. 대화형 워크플로에 유용.

서버는 현재 53개 도구(핵심 42개 + GUI 11개)를 제공합니다. 각 도구는 MCP JSON 프로토콜을 통해 호출되며 AI가 파싱하고 조치를 취할 수 있는 구조화된 데이터를 반환합니다.

---

실행 방법

1. 사전 요구 사항 – Anki 설치, AnkiConnect 플러그인 추가, Node 22.12+ 필요.
2. 설치 옵션
   • npm(글로벌 또는 npx) – npm install -g @ankimcp/anki-mcp-server 실행 후 ankimcp 실행, 또는 npx @ankimcp/anki-mcp-server로 즉시 실행.
   • MCPB 번들 – GitHub 릴리스 페이지에서 .mcpb 파일을 다운로드하고 Claude Desktop에 설치(드래그 앤 드롭 또는 설정 → 확장 기능).
   • 소스에서 – 클론, npm install, npm run build.
3. 전송 선택
   • STDIO – 데스크톱 AI 클라이언트에 가장 적합. 클라이언트가 서버를 하위 프로세스로 시작(ankimcp --stdio). Claude Desktop, Cursor, Cline, Zed, opencode용 구성 스니펫 제공.
   • HTTP – 로컬 웹 서버 실행(ankimcp는 기본적으로 localhost:3000). 웹 기반 AI 도구에 유용.
4. 원격 액세스(AI가 클라우드에서 실행되는 경우)
   • 터널(권장) – ankimcp --tunnel은 관리형 WebSocket 터널 서비스에 연결하고 OAuth 디바이스 흐름으로 인증하며 ChatGPT, Claude.ai 등에 제공할 수 있는 공개 URL을 제공합니다.
   • ngrok – 인증되지 않은 대안 옵션(README에 자세히 설명되지 않음).

---

일반적인 사용 사례 흐름(README 예제에서)

1. 데크 복습 – AI가 sync를 보낸 다음 get_due_cards(데크로 필터링 가능)를 보내고 반환된 카드를 present_card로 반복하고 각 답변 후 rate_card를 호출합니다.
2. 새 카드 만들기 – AI가 modelNames로 노트 유형을 선택하고, RTL 아랍어의 경우 선택적으로 createModel을 호출한 다음 원하는 필드로 addNotes를 호출합니다.
3. 이미지 추가 – AI가 storeMediaFile로 로컬 파일을 업로드하고, guiSelectedNotes + notesInfo로 현재 선택된 노트를 가져온 다음 updateNoteFields로 앞 필드를 업데이트하여 <img> 태그를 삽입합니다.

---

누가 혜택을 받을 수 있나요?

• 플래시카드를 즉시 가져오고, 설명하고, 편집할 수 있는 대화형 튜터를 원하는 학습자.
• 개인 Anki 컬렉션에 프로그래밍 방식으로 액세스해야 하는 사용자 지정 AI 에이전트를 구축하는 개발자.
• LLM 기반 스크립트를 통해 대량 노트 생성 또는 미디어 관리를 자동화하려는 교육자.

---

제한 사항 및 주의 사항(README 기준)

• 서버는 AnkiConnect가 필요 – Anki와 직접 통신하지 않습니다.
• 일부 도구(예: forgetCards, setDueDate)는 복습을 기록하지 않고 일정을 수정하므로 장기 통계에 영향을 줄 수 있습니다.
• 원격 액세스에는 관리형 터널(권장) 또는 별도의 터널링 솔루션이 필요합니다. Anki를 인터넷에 직접 노출하는 것은 권장되지 않습니다.
• 대부분의 사용자에게 AnkiMCP 애드온이 더 간단합니다. 이 저장소는 주로 STDIO 또는 MCPB 번들이 필요한 사람들을 위한 것입니다.

---

빠른 시작(npx를 통한 STDIO)

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

위 JSON을 AI 클라이언트의 적절한 구성 파일(예: Cursor의 ~/.cursor/mcp.json)에 넣으면 클라이언트가 서버를 자동으로 시작합니다.

---

요약: Anki MCP 서버는 잘 정의된 프로토콜을 통해 최신 LLM 기반 어시스턴트가 Anki 플래시카드를 읽고, 편집하고, 관리할 수 있게 하는 Node 기반 브리지로, 로컬 STDIO 및 원격 HTTP/터널 연결을 모두 지원합니다.