AnkiMCP 서버 (애드온)

Model Context Protocol (MCP)를 통해 사용자의 컬렉션을 AI 어시스턴트에 노출하는 Anki 애드온입니다.

이것은 무엇인가요?

AnkiMCP 서버는 Anki 내부에서 로컬 MCP 서버를 실행하여 Claude와 같은 AI 어시스턴트가 사용자의 플래시카드 컬렉션과 상호작용할 수 있도록 합니다. 이를 통해 AI 기반 학습 세션, 카드 생성 및 컬렉션 관리가 가능해집니다.

ankimcp.ai 프로젝트의 일부입니다.

Related MCP server: Anki MCP Server

첫 실행 시 참고 사항

첫 실행 시, 이 애드온은 PyPI에서 pydantic_core(~2MB)를 다운로드합니다. 이는 pydantic_core에 단일 애드온 파일로 번들링할 수 없는 플랫폼별 바이너리(Windows/macOS/Linux)가 포함되어 있기 때문에 필요합니다.

기능

• 로컬 HTTP 서버 - 기본적으로 http://127.0.0.1:3141/에서 실행

• MCP 프로토콜 - 모든 MCP 클라이언트(Claude Desktop 등)와 호환

• 자동 시작 - Anki가 열리면 서버가 자동으로 시작

• 터널 친화적 - Cloudflare Tunnel, ngrok 등과 함께 작동

• 크로스 플랫폼 - macOS, Windows 및 Linux(x64 및 ARM)에서 작동

설치

AnkiWeb에서 설치 (권장)

1. Anki를 열고 *도구 → 애드온 → 애드온 가져오기...*로 이동합니다.

2. 코드 입력: 124672614

3. Anki를 재시작합니다.

GitHub 릴리스에서 설치

1. 릴리스에서 anki_mcp_server.ankiaddon을 다운로드합니다.

2. 더블 클릭하여 설치하거나 *도구 → 애드온 → 파일에서 설치...*를 사용합니다.

3. Anki를 재시작합니다.

NixOS

flakes 사용 (권장)

flake 입력을 추가하고 미리 빌드된 패키지를 사용하세요:

# flake.nix
{
  inputs.anki-mcp.url = "github:ankimcp/anki-mcp-server-addon";

  outputs = { nixpkgs, anki-mcp, ... }: {
    # Option A: Standalone — Anki with the addon pre-installed
    environment.systemPackages = [
      anki-mcp.packages.${system}.default
    ];

    # Option B: Composable with other addons via overlay
    nixpkgs.overlays = [ anki-mcp.overlays.default ];
    environment.systemPackages = [
      (pkgs.anki.withAddons [ pkgs.ankiAddons.anki-mcp-server ])
    ];
  };
}

flakes 미사용

# configuration.nix
{ pkgs, ... }:
let
  python3 = pkgs.python3;

  ankiMcpPythonDeps = python3.withPackages (ps: with ps; [
    mcp pydantic pydantic-settings starlette uvicorn anyio httpx websockets
  ]);

  anki-mcp-server = pkgs.anki-utils.buildAnkiAddon (finalAttrs: {
    pname = "anki-mcp-server";
    version = "0.13.0";
    src = pkgs.fetchFromGitHub {
      owner = "ankimcp";
      repo = "anki-mcp-server-addon";
      rev = "v${finalAttrs.version}";
      hash = ""; # nix will tell you the correct hash on first build
    };
    sourceRoot = "${finalAttrs.src.name}/anki_mcp_server";
  });

  ankiWithMcp = pkgs.anki.withAddons [ anki-mcp-server ];

  ankiWrapped = pkgs.symlinkJoin {
    name = "anki-with-mcp";
    paths = [ ankiWithMcp ];
    nativeBuildInputs = [ pkgs.makeWrapper ];
    postBuild = ''
      wrapProgram $out/bin/anki \
        --prefix PYTHONPATH ':' "${ankiMcpPythonDeps}/${python3.sitePackages}"
    '';
  };
in
{
  environment.systemPackages = [ ankiWrapped ];
}

사용법

Anki를 열면 서버가 자동으로 시작됩니다. *도구 → AnkiMCP 서버 설정...*을 통해 상태를 확인하세요.

Claude Desktop과 연결

Node.js가 설치되어 있어야 합니다. Claude Desktop 설정(~/Library/Application Support/Claude/claude_desktop_config.json, macOS 기준)에 추가하세요:

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3141"]
    }
  }
}

참고: Claude Desktop은 JSON 설정에서 HTTP 서버를 기본적으로 지원하지 않으므로, mcp-remote가 stdio를 통해 연결을 브리지합니다.

Claude Code와 연결

claude mcp add anki --transport http http://127.0.0.1:3141/

설정

Anki의 도구 → 애드온 → AnkiMCP 서버 → 설정을 통해 편집하세요:

{
  "mode": "http",
  "http_port": 3141,
  "http_host": "127.0.0.1",
  "http_path": "",
  "cors_origins": [],
  "cors_expose_headers": ["mcp-session-id", "mcp-protocol-version"],
  "auto_connect_on_startup": true,
  "disabled_tools": [],
  "media_import_dir": "",
  "media_allowed_types": [],
  "media_allowed_hosts": []
}

도구 비활성화

토큰 사용량을 줄이기 위해 AI 클라이언트에서 특정 도구나 작업을 숨깁니다:

{
  "disabled_tools": [
    "sync",
    "card_management:bury",
    "card_management:unbury"
  ]
}

• "tool_name" — 전체 도구를 비활성화

• "tool_name:action" — 다중 작업 도구 내의 특정 작업을 비활성화

비활성화된 도구는 MCP 스키마에서 완전히 제거되므로 AI 클라이언트는 이를 전혀 볼 수 없습니다. 도구/작업 이름에 오타가 있으면 콘솔 경고가 생성됩니다.

사용자 지정 경로

http_path를 설정하여 사용자 지정 경로에서 MCP 엔드포인트를 제공합니다. 터널(Cloudflare, ngrok)을 통해 Anki를 노출할 때 완전히 열린 엔드포인트를 피하는 데 유용합니다:

{
  "http_path": "my-secret-path"
}

서버는 루트 대신 http://localhost:3141/my-secret-path/에서 액세스할 수 있게 됩니다. 기본 동작을 사용하려면 비워 두세요.

CORS 설정

브라우저 기반 MCP 클라이언트(웹 호스팅 MCP Inspector 등)를 허용하려면 허용된 오리진을 추가하세요:

{
  "cors_origins": ["https://inspector.example.com", "http://localhost:5173"]
}

모든 오리진을 허용하려면 ["*"]를 사용하세요(프로덕션 환경에서는 권장하지 않음).

cors_expose_headers 설정은 브라우저가 읽을 수 있는 응답 헤더를 제어합니다. 기본값(mcp-session-id, mcp-protocol-version)은 브라우저에서 MCP Streamable HTTP 프로토콜이 작동하는 데 필요합니다.

미디어 보안

미디어 경로 탐색 취약점을 책임감 있게 공개해 주신 Hideaki Takahashi(컬럼비아 대학교)님께 감사드립니다.

store_media_file 도구는 경로 탐색 및 SSRF 공격을 방지하기 위해 모든 입력을 검증합니다:

• 파일 경로는 MIME 유형 검사를 통해 미디어 파일(이미지, 오디오, 비디오)로만 제한됩니다.

• URL은 http:// 또는 https://를 사용해야 하며 비공개/내부 네트워크를 대상으로 할 수 없습니다.

• 파일명은 경로 탐색 시퀀스를 제거하도록 정리됩니다.

설정을 통한 선택적 강화:

{
  "media_import_dir": "/Users/me/anki-media",
  "media_allowed_types": ["application/pdf"],
  "media_allowed_hosts": ["192.168.1.50", "my-nas.local"]
}

• media_import_dir — 파일 경로 가져오기를 이 디렉토리 트리로 제한(비어 있으면 제한 없음)

• media_allowed_types — 이미지/오디오/비디오 외에 추가 MIME 유형 허용

• media_allowed_hosts — 특정 호스트가 비공개 네트워크 차단을 우회하도록 허용

사용 가능한 도구

필수 도구

FSRS 도구

GUI 도구

이 도구들은 Anki 사용자 인터페이스와 상호작용합니다:

리소스

프롬프트

요구 사항

• Anki 25.07 이상 (Python 3.13 포함)

• Anki 25.02 이하 버전은 Python 3.9를 포함하며, 지원되지 않음 — MCP SDK는 Python 3.10+가 필요함 (#8)

아키텍처

이 애드온은 HTTP 전송(FastMCP + uvicorn)을 사용하여 백그라운드 스레드에서 MCP 서버를 실행합니다. 모든 Anki 작업은 AnkiConnect와 동일하게 검증된 패턴을 따라 큐 시스템을 통해 메인 Qt 스레드로 브리지됩니다.

자세한 내용은 Anki 애드온 개발 문서를 참조하세요.

개발

E2E 테스트 실행

E2E 테스트는 headless-anki를 사용하여 Docker 내의 실제 Anki 인스턴스에 대해 실행됩니다.

# Install test dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

# Build the addon
./package.sh

# Start Anki container
cd .docker && docker compose up -d && cd ..

# Run tests (waits for server automatically)
pytest tests/e2e/ -v

# Stop container
cd .docker && docker compose down

또는 Makefile 바로가기를 사용하세요:

make e2e        # Build, start container, run tests, stop
make e2e-up     # Just start container
make e2e-test   # Just run tests
make e2e-down   # Just stop container

CI

E2E 테스트는 모든 브랜치에 대한 푸시 및 main에 대한 PR 시 자동으로 실행됩니다. .github/workflows/e2e.yml을 참조하세요.

라이선스

AGPL-3.0-or-later

링크

• ankimcp.ai - 프로젝트 홈페이지

• MCP 프로토콜 - Model Context Protocol 사양

• Anki 애드온 문서 - 공식 Anki 애드온 개발 문서