Anki MCP

chính thức

Một máy chủ MCP cho phép các trợ lý AI tương tác với Anki, ứng dụng flashcard lặp lại ngắt quãng.

GitHub
372

Bạn có thể làm gì với Anki MCP?

  • Review due cards in a specific deck — ask the assistant to fetch and present your due cards using get_due_cards and present_card, then record your ratings with rate_card.
  • Batch-create flashcards from a list — provide a set of terms and definitions and have the assistant create up to 100 notes at once via addNotes.
  • Search and update existing notes — find notes with findNotes using Anki query syntax, inspect them with notesInfo, and modify fields with updateNoteFields.
  • Manage note types and styling — create a new note type with createModel, adjust its CSS with updateModelStyling, or modify its card templates with updateModelTemplates.
  • Import media files into your collection — upload an image or audio file from a local path or URL using storeMediaFile and reference it in a note field.

Tài liệu

Máy chủ Anki MCP

Tests npm version

Anki + MCP Integration

Tích hợp liền mạch Anki với trợ lý AI thông qua Giao thức Ngữ cảnh Mô hình

Beta - Dự án này đang trong quá trình phát triển tích cực. API và tính năng có thể thay đổi.

Một máy chủ Giao thức Ngữ cảnh Mô hình (MCP) cho phép trợ lý AI tương tác với Anki, ứng dụng flashcard lặp lại ngắt quãng.

Biến đổi trải nghiệm Anki của bạn với tương tác ngôn ngữ tự nhiên - giống như có một gia sư riêng. Trợ lý AI không chỉ đưa ra câu hỏi và câu trả lời; nó có thể giải thích các khái niệm, làm cho quá trình học tập trở nên hấp dẫn và giống con người hơn, cung cấp ngữ cảnh và thích ứng với phong cách học tập của bạn. Nó có thể tạo và chỉnh sửa ghi chú ngay lập tức, biến các buổi học của bạn thành những cuộc trò chuyện năng động. Sắp có thêm nhiều tính năng!

Ví dụ và Hướng dẫn

Để có hướng dẫn toàn diện, ví dụ thực tế và hướng dẫn từng bước về cách sử dụng máy chủ MCP này với Claude Desktop, hãy truy cập:

ankimcp.ai - Tài liệu đầy đủ với các ví dụ thực tế và trường hợp sử dụng

Xem docs/ để biết tài liệu bổ sung, bao gồm hướng dẫn thiết lập reviewer và bộ thẻ Anki mẫu.

Trường hợp Sử dụng Ví dụ

Ba lời nhắc tiêu biểu cho thấy các luồng công cụ mà máy chủ này hỗ trợ:

  1. "Giúp tôi ôn tập bộ thẻ tiếng Tây Ban Nha." — Trợ lý đồng bộ hóa với AnkiWeb (sync), lấy các thẻ đến hạn (get_due_cards với bộ lọc bộ thẻ), trình bày từng thẻ (present_card) và ghi lại đánh giá của bạn (rate_card). Cuộc trò chuyện học tập tự nhiên với các giải thích được điều chỉnh cho bạn.

  2. "Tạo 10 thẻ từ vựng tiếng Ả Rập với kiểu dáng RTL." — Trợ lý liệt kê các loại ghi chú (modelNames), tạo mô hình RTL tùy chỉnh nếu cần (createModel + updateModelStyling cho CSS phải sang trái), sau đó tạo hàng loạt thẻ (addNotes).

  3. "Nhập hình ảnh này từ thư mục Tải xuống của tôi vào mặt trước của ghi chú đã chọn." — Trợ lý tải lên tệp cục bộ (storeMediaFile với đường dẫn tệp), đọc ghi chú hiện đang được chọn từ trình duyệt (guiSelectedNotes + notesInfo) và cập nhật trường mặt trước bằng thẻ <img> (updateNoteFields).

Công cụ Có sẵn

Máy chủ cung cấp 42 công cụ MCP — 31 công cụ thiết yếu cho các thao tác Anki hàng ngày và 11 công cụ GUI điều khiển giao diện máy tính để bàn Anki cho các quy trình chỉnh sửa/tạo ghi chú.

Công cụ Thiết yếu

Ôn tập & Học tập

  • sync - Đồng bộ hóa với AnkiWeb để lấy dữ liệu mới nhất và đẩy các thay đổi
  • get_due_cards - Lấy các thẻ đến hạn ôn tập, tùy chọn lọc theo bộ thẻ
  • get_cards - Lấy thẻ với bộ lọc linh hoạt theo trạng thái (đến hạn, mới, đang học, tạm dừng, chôn) và bộ thẻ
  • present_card - Hiển thị thẻ để ôn tập với mặt câu hỏi/mặt trước của nó
  • rate_card - Đánh giá hiệu suất thẻ (Lại, Khó, Tốt, Dễ) và lên lịch ôn tập tiếp theo

Quản lý Bộ thẻ

  • listDecks - Liệt kê tất cả các bộ thẻ, tùy chọn kèm thống kê số lượng thẻ mỗi bộ
  • deckStats - Lấy thống kê toàn diện cho một bộ thẻ (số lượng, phân phối độ dễ/khoảng thời gian)
  • createDeck - Tạo một bộ thẻ trống mới (hỗ trợ Parent::Child, tối đa 2 cấp)
  • changeDeck - Di chuyển thẻ sang bộ thẻ khác (tạo mới nếu chưa tồn tại)

Quản lý Ghi chú

  • addNote - Tạo một ghi chú duy nhất với các trường và thẻ được chỉ định
  • addNotes - Tạo hàng loạt tối đa 100 ghi chú chia sẻ cùng bộ thẻ và mô hình (hỗ trợ thành công một phần)
  • findNotes - Tìm kiếm ghi chú bằng cú pháp truy vấn Anki (deck:, tag:, is:due, v.v.)
  • notesInfo - Lấy thông tin chi tiết về ghi chú (trường, thẻ, kiểu dáng CSS)
  • updateNoteFields - Cập nhật các trường ghi chú hiện có (nhận biết CSS, hỗ trợ nội dung HTML)
  • deleteNotes - Xóa ghi chú và tất cả các thẻ liên quan (phá hủy, yêu cầu xác nhận)

Quản lý Thẻ

  • getTags - Lấy tất cả thẻ trong bộ sưu tập (sử dụng trước để tránh trùng lặp)
  • addTags - Thêm thẻ phân cách bằng dấu cách vào các ghi chú được chỉ định
  • removeTags - Xóa thẻ phân cách bằng dấu cách khỏi các ghi chú được chỉ định
  • replaceTags - Đổi tên thẻ trên các ghi chú được chỉ định
  • clearUnusedTags - Xóa thẻ mồ côi không được sử dụng bởi bất kỳ ghi chú nào (phá hủy)

Quản lý Phương tiện

  • getMediaFilesNames - Liệt kê các tệp phương tiện trong collection.media, tùy chọn lọc theo mẫu
  • retrieveMediaFile - Tải xuống tệp phương tiện dưới dạng nội dung base64
  • storeMediaFile - Tải lên phương tiện từ dữ liệu base64, đường dẫn tệp tuyệt đối hoặc URL
  • deleteMediaFile - Xóa tệp phương tiện khỏi collection.media (phá hủy)

💡 Thực hành Tốt nhất cho Hình ảnh:

  • ✅ Sử dụng đường dẫn tệp (ví dụ: /Users/you/image.png) - Nhanh và hiệu quả
  • ✅ Sử dụng URL (ví dụ: https://example.com/image.jpg) - Tải xuống trực tiếp
  • ❌ Tránh base64 - Cực kỳ chậm và không hiệu quả về token

Chỉ cần cho Claude biết hình ảnh ở đâu, và nó sẽ tự động xử lý tải lên bằng phương pháp hiệu quả nhất.

Quản lý Mô hình/Mẫu

  • modelNames - Liệt kê tất cả các loại ghi chú/mô hình có sẵn
  • modelFieldNames - Lấy tên trường cho một loại ghi chú cụ thể
  • modelStyling - Lấy thông tin kiểu dáng CSS cho một loại ghi chú
  • modelTemplates - Lấy các mẫu thẻ (HTML Mặt trước và Mặt sau) cho một loại ghi chú
  • createModel - Tạo một loại ghi chú mới với các trường tùy chỉnh, mẫu thẻ và CSS (ví dụ: mô hình RTL)
  • updateModelStyling - Cập nhật kiểu dáng CSS cho một loại ghi chú hiện có (áp dụng cho tất cả thẻ của nó)
  • updateModelTemplates - Cập nhật mẫu thẻ (HTML Mặt trước và Mặt sau) cho một loại ghi chú hiện có (áp dụng cho tất cả thẻ của nó)
  • addModelField - Thêm trường mới vào loại ghi chú hiện có (thêm vào cuối hoặc chèn vào vị trí cụ thể)
  • removeModelField - Xóa trường khỏi loại ghi chú hiện có (xóa nội dung của nó khỏi tất cả ghi chú; yêu cầu xác nhận rõ ràng)
  • renameModelField - Đổi tên trường trong loại ghi chú hiện có (mẫu thẻ tham chiếu đến tên cũ phải được cập nhật riêng)
  • repositionModelField - Thay đổi vị trí của trường trong loại ghi chú hiện có

Thống kê

  • collection_stats - Thống kê tổng hợp trên tất cả các bộ thẻ với phân tích theo từng bộ
  • review_stats - Phân tích lịch sử ôn tập (mẫu thời gian, chỉ số ghi nhớ, chuỗi học tập)

Công cụ GUI

Các công cụ điều khiển giao diện máy tính để bàn Anki. Dành cho quy trình chỉnh sửa/tạo ghi chú và quản lý bộ thẻ, không dành cho các buổi ôn tập.

  • guiBrowse - Mở Trình duyệt Thẻ và tìm kiếm thẻ
  • guiSelectCard - Chọn một thẻ cụ thể trong Trình duyệt Thẻ
  • guiSelectedNotes - Lấy ID của các ghi chú hiện đang được chọn trong Trình duyệt Thẻ
  • guiAddCards - Mở hộp thoại Thêm Thẻ với chi tiết ghi chú được đặt trước
  • guiEditNote - Mở trình chỉnh sửa ghi chú cho một ghi chú cụ thể
  • guiDeckOverview - Mở hộp thoại Tổng quan Bộ thẻ cho một bộ thẻ cụ thể
  • guiDeckBrowser - Mở hộp thoại Trình duyệt Bộ thẻ
  • guiCurrentCard - Lấy thông tin về thẻ hiện tại trong chế độ ôn tập
  • guiShowQuestion - Hiển thị mặt câu hỏi của thẻ hiện tại
  • guiShowAnswer - Hiển thị mặt trả lời của thẻ hiện tại
  • guiUndo - Hoàn tác hành động cuối cùng trong Anki

Điều kiện Tiên quyết

Cài đặt

Có một số cách để đưa máy chủ vào máy của bạn. Sau khi cài đặt, hãy đến Kết nối Ứng dụng AI để kết nối nó với trợ lý AI của bạn — cục bộ hoặc từ xa.

npm (toàn cục hoặc npx)

Cách cài đặt đa năng, phù hợp với bất kỳ ứng dụng MCP nào khởi chạy trực tiếp.

Cài đặt toàn cục cho các ứng dụng chạy lệnh ankimcp:

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

Hoặc chạy theo yêu cầu mà không cần cài đặt:

npx @ankimcp/anki-mcp-server

Gói MCPB (Khuyến nghị cho Claude Desktop)

Cách dễ nhất để cài đặt máy chủ MCP này cho Claude Desktop:

  1. Tải xuống gói .mcpb mới nhất từ trang Phát hành
  2. Trong Claude Desktop, cài đặt tiện ích mở rộng:
    • Phương pháp 1: Vào Cài đặt → Tiện ích mở rộng, sau đó kéo và thả tệp .mcpb
    • Phương pháp 2: Vào Cài đặt → Nhà phát triển → Tiện ích mở rộng → Cài đặt Tiện ích mở rộng, sau đó chọn tệp .mcpb
  3. Cấu hình URL AnkiConnect nếu cần (mặc định là http://localhost:8765)
  4. Khởi động lại Claude Desktop

Vậy thôi! Gói bao gồm mọi thứ cần thiết để chạy máy chủ cục bộ.

Dành cho người đánh giá Thư mục MCP của Anthropic: hướng dẫn từng bước từ đầu đến tích hợp với bộ thẻ mẫu được điền sẵn có trong docs/reviewer-setup.md.

Cài đặt từ Mã nguồn (để phát triển)

Để phát triển hoặc sử dụng nâng cao:

npm install
npm run build

Kết nối Ứng dụng AI

Có hai cách để trợ lý AI có thể kết nối với máy chủ này, tùy thuộc vào nơi trợ lý chạy:

  • Cục bộ — máy chủ chạy trên cùng máy với ứng dụng AI (Claude Desktop, Cursor, Cline, Zed hoặc phiên trình duyệt cục bộ). Sử dụng STDIO cho ứng dụng MCP máy tính để bàn, HTTP cho công cụ web cục bộ.
  • Từ xa — AI được lưu trữ/từ xa (ví dụ: ChatGPT hoặc Claude.ai trên đám mây) cần kết nối với Anki đang chạy trên máy cục bộ của bạn. Sử dụng Đường hầm được quản lý (✅ khuyến nghị — có xác thực) hoặc, như một giải pháp thay thế nhẹ hơn không xác thực, ngrok.

Cục bộ

Máy chủ chạy trên cùng máy tính với ứng dụng AI của bạn và giao tiếp với AnkiConnect trên localhost.

STDIO (tích hợp cục bộ chính)

STDIO là phương thức truyền tải tiêu chuẩn cho các ứng dụng MCP máy tính để bàn cục bộ — Claude Desktop, Cursor IDE, Cline, Zed Editor và các ứng dụng khác. Ứng dụng khởi chạy máy chủ như một tiến trình con và giao tiếp qua đầu vào/đầu ra tiêu chuẩn.

Ứng dụng được Hỗ trợ:

  • Claude Desktop
  • Cursor IDE - Trình soạn thảo mã hỗ trợ AI
  • Cline - Tiện ích mở rộng VS Code cho trợ lý AI
  • Zed Editor - Trình soạn thảo mã nhanh, hiện đại
  • Các ứng dụng MCP khác hỗ trợ truyền tải STDIO

Đối với Claude Desktop, gói MCPB là cách dễ nhất. Đối với các ứng dụng khác, cấu hình gói npm với cờ --stdio.

Cấu hình - Chọn một phương pháp:

Phương pháp 1: Sử dụng npx (khuyến nghị - không cần cài đặt)

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

Phương pháp 2: Sử dụng cài đặt toàn cục

Đầu tiên, cài đặt toàn cục:

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

Sau đó cấu hình:

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

Vị trí tệp cấu hình:

  • Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) hoặc %USERPROFILE%\.cursor\mcp.json (Windows)
  • Cline: Có thể truy cập qua giao diện cài đặt trong VS Code
  • Zed Editor: Cài đặt dưới dạng tiện ích mở rộng MCP thông qua thị trường tiện ích mở rộng

Đối với các tính năng cụ thể của ứng dụng và khắc phục sự cố, hãy tham khảo tài liệu của ứng dụng MCP của bạn. Xem thêm Kết nối với Claude Desktop để biết cấu hình trỏ trực tiếp đến dist/main-stdio.js đã được xây dựng.

HTTP (AI dựa trên web cục bộ)

Chế độ HTTP chạy máy chủ như một máy chủ web cục bộ sử dụng giao thức HTTP Có thể Truyền phát MCP. Đây là phương thức truyền tải mà công cụ AI dựa trên web giao tiếp khi trỏ đến máy của bạn, và cũng là những gì các tùy chọn Từ xa phơi bày ra thế giới bên ngoài. Tự nó, chế độ HTTP chỉ liên kết với localhost.

Liên kết ra ngoài localhost? Nếu bạn truyền --host 0.0.0.0 (hoặc chạy sau proxy ngược/tên miền công cộng), máy chủ chỉ chấp nhận tiêu đề loopback Host theo mặc định để bảo vệ chống rebinding DNS — đặt ALLOWED_HOSTS thành (các) tên máy chủ mà ứng dụng sử dụng. Xem Cấu hình Chế độ HTTP.

Thiết lập - Chọn một phương pháp:

Phương pháp 1: Sử dụng npx (khuyến nghị - không cần cài đặt)

# 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

Phương pháp 2: Sử dụng cài đặt toàn cục

# 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

Phương pháp 3: Cài đặt từ mã nguồn (để phát triển)

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

Để làm cho máy chủ HTTP cục bộ có thể truy cập được bởi AI được lưu trữ trên đám mây, hãy sử dụng một trong các tùy chọn Từ xa bên dưới.

Từ xa

Một AI được lưu trữ/từ xa (chẳng hạn như ChatGPT hoặc Claude.ai chạy trên đám mây) không thể truy cập trực tiếp localhost. Các tùy chọn này giúp bạn đưa Anki cục bộ của mình lên internet để trợ lý từ xa có thể giao tiếp với nó.

Đường hầm (✅ Khuyến nghị)

Lộ trình từ xa được khuyến nghị — đã xác thực & bảo mật. Không giống như cổng công khai thô, chế độ đường hầm yêu cầu bạn đăng nhập (luồng thiết bị OAuth 2.0), vì vậy điểm cuối không mở cho bất kỳ ai đoán được URL.

Chế độ đường hầm cho phép các trợ lý AI dựa trên web truy cập Anki cục bộ của bạn mà không cần bạn tự chạy đường hầm. Máy chủ kết nối ra dịch vụ đường hầm AnkiMCP được quản lý (wss://tunnel.ankimcp.ai) qua WebSocket và được gán một URL công khai. Xác thực được tích hợp sẵn — không cần tài khoản ngrok hoặc quy trình đường hầm riêng biệt, và bạn chỉ cần đăng nhập một lần.

Đăng nhập (luồng thiết bị OAuth):

Chế độ đường hầm sử dụng Cấp quyền thiết bị OAuth 2.0. Việc đăng nhập sẽ tự động mở trình duyệt của bạn đến trang phê duyệt với mã đã được nhúng sẵn trong URL — không cần nhập gì, chỉ cần phê duyệt. (Nếu không thể mở trình duyệt, thiết bị đầu cuối sẽ in URL xác minh và mã để bạn nhập thủ công như một phương án dự phòng.) Khi thành công, thông tin xác thực được lưu vào ~/.ankimcp/credentials.json (quyền tệp 0600).

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

# Clear saved credentials
ankimcp --logout

Khởi động đường hầm:

# 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

Nếu chưa có thông tin xác thực, --tunnel sẽ tự động bắt đầu luồng đăng nhập trước, sau đó tiếp tục vào đường hầm. Tính năng tự động đăng nhập này yêu cầu thiết bị đầu cuối tương tác — khi stdout không phải là TTY (systemd, Docker không đầu, CI), máy chủ sẽ nhanh chóng thất bại và yêu cầu bạn chạy ankimcp --login trước. Sau khi kết nối, URL đường hầm công khai sẽ được in ra; nhấn Ctrl+C để ngắt kết nối. Chia sẻ URL đó với trợ lý AI của bạn.

Biến môi trường chế độ đường hầm:

BiếnMô tảMặc định
TUNNEL_SERVER_URLURL WebSocket của máy chủ đường hầm (giá trị cờ --tunnel/--login ghi đè lên giá trị này)wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_IDID ứng dụng khách OAuth cho luồng thiết bị. Nâng cao — chỉ cần khi trỏ đến dịch vụ đường hầm/xác thực tự lưu trữ.(tích hợp sẵn)

Các điểm cuối xác thực luồng thiết bị (/auth/device, /auth/token) được dẫn xuất từ TUNNEL_SERVER_URL, vì vậy việc trỏ --tunnel (hoặc TUNNEL_SERVER_URL) đến một máy chủ khác cũng sẽ chuyển xác thực đến máy chủ đó.

Cách thức hoạt động: Chế độ đường hầm chạy máy chủ MCP trong tiến trình phía sau một truyền tải trong bộ nhớ (McpModule được khởi động mà không có truyền tải tích hợp sẵn). TunnelMcpService kết nối truyền tải trong bộ nhớ đó với máy chủ MCP, và TunnelClient cầu nối nó với dịch vụ đường hầm từ xa qua WebSocket — chuyển tiếp các yêu cầu MCP vào và phản hồi ra. AnkiConnect vẫn chỉ được truy cập trên máy cục bộ của bạn.

ngrok (phương án thay thế không xác thực)

Nếu bạn muốn đưa chế độ HTTP cục bộ ra công khai mà không cần tài khoản trên đường hầm được quản lý, cờ --ngrok tích hợp sẵn sẽ khởi chạy một tiến trình con ngrok (src/services/ngrok.service.ts) và in URL công khai trong biểu ngữ khởi động:

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

Lộ trình này không được xác thực — bất kỳ ai có URL đều có thể truy cập Anki của bạn, vì vậy nó kém bảo mật hơn Đường hầm. Hãy ưu tiên Đường hầm trừ khi bạn có lý do cụ thể để tự quản lý điểm cuối ngrok của mình. (Yêu cầu cài đặt ngrok toàn cục và mã thông báo xác thực.)

Cờ --ngrok khởi chạy ngrok với --host-header=rewrite, vì vậy ngrok ghi lại Host ngược dòng thành localhost trước khi chuyển tiếp. Điều đó giữ các yêu cầu trong danh sách cho phép máy chủ loopback (xem bảo vệ DNS-rebinding) mà bạn không cần thêm miền *.ngrok công khai vào ALLOWED_HOSTS. Nếu bạn tự chạy ngrok thủ công, hãy sử dụng cùng một cờ — ngrok http --host-header=rewrite 3000 — nếu không ngrok sẽ chuyển tiếp tên máy chủ ngrok công khai dưới dạng Host và máy chủ sẽ từ chối nó với 403.

Tùy chọn CLI (tất cả các chế độ)

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

Chế độ Chỉ đọc (tất cả các chế độ)

Cờ --read-only ngăn chặn mọi sửa đổi đối với bộ sưu tập Anki của bạn. Khi được bật:

  • Tất cả các thao tác đọc hoạt động bình thường (duyệt bộ thẻ, xem thẻ, tìm kiếm ghi chú)
  • Các thao tác ôn tập được phép (đồng bộ hóa, answerCards, suspend/unsuspend)
  • Các sửa đổi nội dung bị chặn (addNote, deleteNotes, createDeck, updateNoteFields, v.v.)
  • Hữu ích để khám phá dữ liệu Anki một cách an toàn mà không có nguy cơ thay đổi ngoài ý muốn
# 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

Bạn cũng có thể bật chế độ chỉ đọc qua biến môi trường:

READ_ONLY=true ankimcp

Hoặc trong cấu hình máy khách MCP:

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

Kết nối với Claude Desktop (Chế độ Cục bộ)

Bạn có thể cấu hình máy chủ trong Claude Desktop bằng cách:

  • Vào: Cài đặt → Nhà phát triển → Chỉnh sửa Cấu hình
  • Hoặc chỉnh sửa thủ công tệp cấu hình

Cấu hình

Thêm phần sau vào cấu hình Claude Desktop của bạn:

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

Thay thế /path/to/anki-mcp-server bằng đường dẫn dự án thực tế của bạn.

Vị trí Tệp Cấu hình

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

Để biết thêm chi tiết, hãy xem tài liệu MCP chính thức.

Biến Môi trường (Tùy chọn)

BiếnMô tảMặc định
ANKI_CONNECT_URLURL AnkiConnecthttp://localhost:8765
ANKI_CONNECT_API_VERSIONPhiên bản API6
ANKI_CONNECT_API_KEYKhóa API nếu được cấu hình trong AnkiConnect-
ANKI_CONNECT_TIMEOUTThời gian chờ yêu cầu tính bằng ms5000
READ_ONLYBật chế độ chỉ đọc (true hoặc 1)false
ALLOWED_HOSTSChế độ HTTP: các giá trị tiêu đề Host bổ sung để chấp nhận ngoài loopback (tên máy chủ được phân tách bằng dấu phẩy). Yêu cầu khi liên kết với địa chỉ LAN/công khai hoặc chạy phía sau proxy ngược. Xem Cấu hình Chế độ HTTP.chỉ loopback
ALLOWED_ORIGINSChế độ HTTP: danh sách cho phép các mẫu Origin/Referer của trình duyệt được phân tách bằng dấu phẩy (hỗ trợ ký tự đại diện, ví dụ: https://*.ngrok.io).http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URLURL WebSocket của máy chủ đường hầm (chỉ chế độ đường hầm)wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPESCác loại MIME bổ sung để cho phép nhập đường dẫn tệp (phân tách bằng dấu phẩy, ví dụ: application/pdf)-
MEDIA_IMPORT_DIRHạn chế nhập đường dẫn tệp vào thư mục này-
MEDIA_ALLOWED_HOSTSCho phép các máy chủ mạng riêng cụ thể để nhập URL (phân tách bằng dấu phẩy, ví dụ: 192.168.1.50,my-nas)-

Ví dụ Sử dụng

Tìm kiếm và Cập nhật Ghi chú

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

Ví dụ Cú pháp Truy vấn Anki

Công cụ findNotes hỗ trợ cú pháp truy vấn mạnh mẽ của Anki:

  • "deck:DeckName" - Tất cả ghi chú trong một bộ thẻ cụ thể
  • "tag:important" - Ghi chú có thẻ "important"
  • "is:due" - Thẻ đến hạn ôn tập
  • "is:new" - Thẻ mới chưa được học
  • "added:7" - Ghi chú được thêm trong 7 ngày qua
  • "front:hello" - Ghi chú có "hello" trong trường mặt trước
  • "flag:1" - Ghi chú có cờ đỏ
  • "prop:due<=2" - Thẻ đến hạn trong vòng 2 ngày
  • "deck:Spanish tag:verb" - Ghi chú bộ thẻ tiếng Tây Ban Nha có thẻ động từ (VÀ)
  • "deck:Spanish OR deck:French" - Ghi chú từ một trong hai bộ thẻ

Ghi chú Quan trọng

Xử lý CSS và HTML

  • Công cụ notesInfo trả về thông tin kiểu dáng CSS để nhận thức kết xuất phù hợp
  • Công cụ updateNoteFields hỗ trợ nội dung HTML trong các trường và bảo toàn kiểu dáng CSS
  • Mỗi mô hình ghi chú có kiểu dáng CSS riêng - sử dụng modelStyling để lấy CSS cụ thể cho mô hình

Cảnh báo Cập nhật

⚠️ QUAN TRỌNG: Khi sử dụng updateNoteFields, KHÔNG xem ghi chú trong trình duyệt của Anki khi đang cập nhật, nếu không các trường sẽ không được cập nhật đúng cách. Đóng trình duyệt hoặc chuyển sang ghi chú khác trước khi cập nhật. Xem Các vấn đề đã biết để biết thêm chi tiết.

An toàn khi Xóa

Công cụ deleteNotes yêu cầu xác nhận rõ ràng (confirmDeletion: true) để ngăn chặn việc xóa ngoài ý muốn. Xóa một ghi chú sẽ xóa vĩnh viễn TẤT CẢ các thẻ liên quan.

Bảo mật

Xác thực Đường dẫn Tệp Phương tiện và URL

Các công cụ phương tiện (storeMediaFile, retrieveMediaFile, deleteMediaFile) và các trường âm thanh/hình ảnh updateNoteFields bao gồm xác thực bảo mật để ngăn chặn việc lạm dụng thông qua tiêm nhiễm lời nhắc:

  • Nhập đường dẫn tệp bị hạn chế chỉ đối với các loại tệp phương tiện (hình ảnh, âm thanh, video). Các tệp không phải phương tiện (ví dụ: khóa SSH, thông tin xác thực, cấu hình shell) bị từ chối dựa trên loại MIME. Cấu hình MEDIA_ALLOWED_TYPES để cho phép các loại tệp bổ sung, hoặc MEDIA_IMPORT_DIR để hạn chế nhập vào một thư mục cụ thể.
  • Nhập URL được xác thực chống lại các cuộc tấn công SSRF. Các yêu cầu đến mạng riêng (10.x, 172.16.x, 192.168.x), loopback (127.x), liên kết cục bộ (169.254.x) và các lược đồ không phải HTTP(S) đều bị chặn. Cấu hình MEDIA_ALLOWED_HOSTS để cho phép các máy chủ mạng riêng cụ thể.
  • Tên tệp được làm sạch để ngăn chặn việc vượt qua đường dẫn (ví dụ: các chuỗi ../../ bị loại bỏ).

Các biện pháp bảo vệ này áp dụng cho storeMediaFile, retrieveMediaFile, deleteMediaFile và các trường âm thanh/hình ảnh updateNoteFields.

Lỗ hổng vượt qua đường dẫn được báo cáo bởi Hideaki Takahashi.

Bảo vệ DNS-Rebinding (truyền tải HTTP)

Khi chạy ở chế độ HTTP, máy chủ xác thực tiêu đề Host trên mỗi yêu cầu. Theo mặc định, chỉ các máy chủ loopback (localhost, 127.0.0.1, ::1) được chấp nhận, bất kể cổng. Host là tiêu đề bị trình duyệt cấm, vì vậy một trang web độc hại không thể giả mạo nó — điều này đóng đường dẫn DNS-rebinding nơi một trang bị rebind truy cập máy chủ cục bộ với Host giả mạo và không có Origin, và truy cập các công cụ MCP. Một Host không được phép sẽ bị từ chối với 403.

Nếu bạn liên kết với 0.0.0.0, chạy phía sau proxy ngược hoặc đưa ra miền đường hầm công khai, hãy đặt ALLOWED_HOSTS (tên máy chủ được phân tách bằng dấu phẩy) để cho phép các máy chủ đó. Khi tạo đường hầm với ngrok, máy chủ sử dụng --host-header=rewrite, vì vậy ngược dòng vẫn thấy một Host loopback. Xem Cấu hình Chế độ HTTP để biết danh sách đầy đủ các tùy chọn.

Lỗ hổng DNS-rebinding được báo cáo bởi avishaigo-commits và yotampe-pluto.

Chính sách Quyền riêng tư

Máy chủ MCP này chạy cục bộ trên máy của bạn và không thu thập bất kỳ dữ liệu đo lường, phân tích hoặc sử dụng nào.

Chính sách đầy đủ: https://ankimcp.ai/privacy/

  • Thu thập dữ liệu: Máy chủ không thu thập gì cả. Nó ủy quyền các yêu cầu giữa trợ lý AI của bạn và plugin AnkiConnect cục bộ.
  • Sử dụng / lưu trữ: Không có lưu trữ phía máy chủ. Tất cả dữ liệu thẻ ghi nhớ vẫn nằm trong cài đặt Anki của bạn trên thiết bị của chính bạn.
  • Chia sẻ với bên thứ ba: Không. Máy chủ chỉ giao tiếp với URL AnkiConnect mà bạn cấu hình (mặc định: localhost). Nếu bạn bật đồng bộ AnkiWeb tích hợp sẵn của Anki, điều đó xảy ra giữa cài đặt Anki của bạn và AnkiWeb trực tiếp — nằm ngoài phạm vi của máy chủ này.
  • Lưu giữ: Không áp dụng — không có dữ liệu nào được lưu giữ phía máy chủ.
  • Liên hệ: support@ankimcp.ai

Các vấn đề đã biết

Để biết danh sách đầy đủ các vấn đề và hạn chế đã biết, vui lòng truy cập tài liệu của chúng tôi:

Tài liệu về các vấn đề đã biết

Hạn chế Nghiêm trọng

Cập nhật Ghi chú Thất bại Khi Được Xem trong Trình duyệt

⚠️ QUAN TRỌNG: Khi cập nhật ghi chú bằng updateNoteFields, việc cập nhật sẽ âm thầm thất bại nếu ghi chú hiện đang được xem trong cửa sổ trình duyệt của Anki. Đây là một hạn chế ngược dòng của AnkiConnect.

Giải pháp thay thế: Luôn đóng trình duyệt hoặc điều hướng đến một ghi chú khác trước khi cập nhật.

Để biết thêm chi tiết và các vấn đề đã biết khác, hãy xem tài liệu đầy đủ.

Khắc phục sự cố

Lỗi ERR_REQUIRE_ESM

Nếu bạn thấy lỗi như:

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

Điều này có nghĩa là phiên bản Node.js của bạn không được hỗ trợ. Máy chủ yêu cầu Node.js 22.12.0+.

Lưu ý: Thời gian chạy được hỗ trợ tối thiểu là Node.js 22.12.0. Node.js 20 (Iron) đã hết vòng đời vào ngày 30-04-2026 và không còn được hỗ trợ.

Kiểm tra phiên bản của bạn:

node --version

Giải pháp: Cập nhật Node.js lên phiên bản 22.12.0+. Bạn có thể tải xuống từ nodejs.org hoặc sử dụng trình quản lý phiên bản như nvm.

Phát triển

Chế độ Truyền tải

Máy chủ này hỗ trợ ba chế độ truyền tải MCP thông qua các điểm vào riêng biệt:

Chế độ STDIO (Mặc định)

  • Dành cho các máy khách MCP cục bộ như Claude Desktop
  • Sử dụng đầu vào/đầu ra tiêu chuẩn để giao tiếp
  • Điểm vào: dist/main-stdio.js
  • Chạy: npm run start:prod:stdio hoặc node dist/main-stdio.js
  • Gói MCPB: Sử dụng chế độ STDIO

Chế độ HTTP (HTTP có thể truyền trực tuyến)

  • Dành cho các máy khách MCP từ xa và tích hợp dựa trên web
  • Sử dụng giao thức MCP Streamable HTTP
  • Điểm vào: dist/main-http.js
  • Chạy: npm run start:prod:http hoặc node dist/main-http.js
  • Cổng mặc định: 3000 (có thể cấu hình qua biến môi trường PORT)
  • Máy chủ mặc định: 127.0.0.1 (có thể cấu hình qua biến môi trường HOST)
  • Điểm cuối MCP: http://127.0.0.1:3000/ (đường dẫn gốc)

Chế độ Đường hầm (Đường hầm WebSocket được Quản lý)

  • Dành cho các trợ lý AI dựa trên web thông qua dịch vụ đường hầm AnkiMCP được quản lý, với xác thực tích hợp sẵn
  • Máy chủ MCP chạy trong tiến trình phía sau một truyền tải trong bộ nhớ; TunnelMcpService kết nối nó với máy chủ MCP và TunnelClient cầu nối nó với dịch vụ đường hầm qua WebSocket
  • Điểm vào: dist/main-tunnel.js
  • Chạy: node dist/main-tunnel.js --tunnel (hoặc ankimcp --tunnel)
  • Xác thực: ankimcp --login / ankimcp --logout; thông tin xác thực được lưu tại ~/.ankimcp/credentials.json (0600)
  • Phát triển: npm run start:dev:tunnel (chế độ theo dõi, chạy --tunnel --debug)

Xây dựng

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

main-stdio.js, main-http.js và main-tunnel.js đều được xây dựng vào cùng thư mục dist/. Chọn cái để chạy dựa trên nhu cầu của bạn.

Cấu hình Chế độ HTTP

Biến Môi trường:

  • PORT - Cổng máy chủ HTTP (mặc định: 3000)
  • HOST - Địa chỉ liên kết (mặc định: 127.0.0.1 chỉ cho localhost)
  • ALLOWED_HOSTS - Các giá trị tiêu đề Host bổ sung được phân tách bằng dấu phẩy để chấp nhận ngoài tập loopback tích hợp sẵn (localhost, 127.0.0.1, ::1). Chỉ tên máy chủ và không phụ thuộc cổng. Mặc định: chỉ loopback.
  • ALLOWED_ORIGINS - Danh sách cho phép các mẫu Origin/Referer của trình duyệt được phân tách bằng dấu phẩy; hỗ trợ ký tự đại diện (ví dụ: https://*.ngrok.io). Mặc định: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
  • LOG_LEVEL - Mức ghi nhật ký (mặc định: info)

Bảo mật:

  • Xác thực tiêu đề Host (bảo vệ chống DNS-rebinding) — mọi yêu cầu HTTP phải mang tiêu đề Host khớp với danh sách cho phép. Theo mặc định, chỉ các máy chủ loopback (localhost, 127.0.0.1, ::1) được chấp nhận, bất kể cổng. Host là tiêu đề bị trình duyệt cấm, vì vậy một trang web độc hại không thể giả mạo nó — điều này đóng đường dẫn DNS-rebinding nơi một trang bị rebind tiếp cận máy chủ với Host giả mạo và không có Origin. Host không được phép sẽ bị từ chối với 403.
  • Xác thực tiêu đề Origin — các yêu cầu từ trình duyệt có Origin/Referer hiện diện nhưng không được phép sẽ bị từ chối. Các yêu cầu không có Origin (curl, Postman, máy khách MCP-over-HTTP) được cho phép; xác thực Host là biện pháp phòng thủ chống lại rebinding.
  • Liên kết với localhost (127.0.0.1) theo mặc định.
  • Không có xác thực trong phiên bản hiện tại (hỗ trợ OAuth đang được lên kế hoạch).

Đưa chế độ HTTP ra ngoài localhost — nếu bạn liên kết với địa chỉ LAN/công cộng hoặc đặt máy chủ sau proxy ngược hoặc tên miền công cộng, bạn phải đặt ALLOWED_HOSTS thành (các) tên máy chủ mà máy khách sẽ sử dụng, nếu không mọi yêu cầu không phải loopback sẽ bị từ chối với 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

Khi bạn liên kết với 0.0.0.0/:: mà không có ALLOWED_HOSTS, máy chủ ghi cảnh báo khởi động rằng chỉ các tiêu đề Host loopback mới được chấp nhận.

Docker / proxy ngược / tên miền công cộng: quy tắc tương tự được áp dụng. Trong Docker, các yêu cầu thường đến với tên máy chủ đã xuất bản của container hoặc Host của proxy, vì vậy hãy đặt ALLOWED_HOSTS cho phù hợp. Một proxy ngược (nginx, Caddy, Traefik) nên chuyển tiếp Host gốc và có tên máy chủ đó được liệt kê trong ALLOWED_HOSTS, hoặc viết lại Host ngược dòng thành localhost. Tích hợp --ngrok tích hợp sẵn xử lý việc này tự động (xem bên dưới).

Ví dụ: Chạy các Chế độ

# 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

Xây dựng Gói MCPB

Để tạo một gói MCPB có thể phân phối:

npm run mcpb:bundle

Lệnh này sẽ:

  1. Đồng bộ phiên bản từ package.json sang manifest.json
  2. Xóa các tệp .mcpb cũ
  3. Xây dựng dự án TypeScript
  4. Đóng gói dist/ và node_modules/ vào một tệp .mcpb
  5. Chạy mcpb clean để loại bỏ devDependencies (tối ưu hóa gói từ ~47MB xuống ~10MB)

Tệp đầu ra sẽ được đặt tên là anki-mcp-server-X.X.X.mcpb và có thể được phân phối để cài đặt một cú nhấp chuột.

Những gì được Đóng gói

Gói MCPB bao gồm:

  • JavaScript đã biên dịch (thư mục dist/ - bao gồm tất cả ba điểm vào)
  • Chỉ các phụ thuộc sản xuất (node_modules/ - devDependencies bị loại bỏ bởi mcpb clean)
  • Siêu dữ liệu gói (package.json)
  • Cấu hình kê khai (manifest.json - được cấu hình để sử dụng main-stdio.js)
  • Biểu tượng (icon.png)

Các tệp nguồn, kiểm thử và cấu hình phát triển được tự động loại trừ qua .mcpbignore.

Ghi nhật ký trong Claude Desktop

Khi chạy dưới dạng tiện ích mở rộng MCPB trong Claude Desktop, nhật ký được ghi vào:

Vị trí Nhật ký: ~/Library/Logs/Claude/ (macOS)

Nhật ký được chia thành nhiều tệp:

  • main.log - Nhật ký ứng dụng Claude Desktop chung
  • mcp-server-Anki MCP Server.log - Tin nhắn giao thức MCP cho tiện ích mở rộng này
  • mcp.log - Nhật ký MCP kết hợp từ tất cả các máy chủ

Lưu ý: Đầu ra của trình ghi nhật ký pino (các thông báo INFO, ERROR, WARN từ mã máy chủ) đi đến stderr và xuất hiện trong các tệp nhật ký dành riêng cho MCP. Claude Desktop xác định tệp nhật ký nào nhận thông báo nào, nhưng nói chung:

  • Khởi động ứng dụng và giao tiếp giao thức MCP → Nhật ký dành riêng cho MCP
  • Ghi nhật ký nội bộ máy chủ (pino) → Cả nhật ký dành riêng cho MCP và đôi khi là main.log

Để xem nhật ký theo thời gian thực:

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

Gỡ lỗi Máy chủ MCP

Bạn có thể gỡ lỗi máy chủ MCP bằng MCP Inspector và gắn trình gỡ lỗi từ IDE của bạn (WebStorm, VS Code, v.v.).

Lưu ý cho Chế độ HTTP: Khi kiểm thử chế độ HTTP (HTTP có thể truyền trực tuyến) với MCP Inspector, hãy sử dụng "Connection Type: Via Proxy" để tránh lỗi CORS.

Bước 1: Cấu hình Máy chủ Gỡ lỗi trong MCP Inspector

mcp-inspector-config.json đã bao gồm cấu hình máy chủ gỡ lỗi:

{
  "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"
    }
  }
}

Bước 2: Khởi động Máy chủ Gỡ lỗi

Chạy MCP Inspector với máy chủ gỡ lỗi:

npm run inspector:debug

Điều này sẽ khởi động máy chủ với gỡ lỗi Node.js được bật trên cổng 9229 và tạm dừng thực thi ở dòng đầu tiên.

Bước 3: Gắn Trình gỡ lỗi từ IDE của Bạn

WebStorm
  1. Đi tới Run → Edit Configurations
  2. Thêm cấu hình Attach to Node.js/Chrome mới
  3. Đặt cổng thành 9229
  4. Nhấp Debug để gắn
VS Code
  1. Mở bảng Debug (Ctrl+Shift+D / Cmd+Shift+D)
  2. Chọn cấu hình Debug MCP Server (Attach)
  3. Nhấn F5 để gắn

Bước 4: Đặt Điểm dừng và Gỡ lỗi

Sau khi được gắn, bạn có thể:

  • Đặt điểm dừng trong các tệp nguồn TypeScript của bạn
  • Bước qua thực thi mã
  • Kiểm tra biến và ngăn xếp cuộc gọi
  • Sử dụng bảng điều khiển gỡ lỗi để đánh giá biểu thức

Trình gỡ lỗi sẽ hoạt động với bản đồ nguồn, cho phép bạn gỡ lỗi mã TypeScript gốc thay vì JavaScript đã biên dịch.

Gỡ lỗi với Claude Desktop

Bạn cũng có thể gỡ lỗi máy chủ MCP khi nó chạy bên trong Claude Desktop bằng cách bật trình gỡ lỗi Node.js và gắn IDE của bạn.

Bước 1: Cấu hình Claude Desktop để Gỡ lỗi

Cập nhật cấu hình Claude Desktop của bạn để bật gỡ lỗi:

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"
      }
    }
  }
}

Thay đổi chính: Thêm --inspect=9229 trước đường dẫn đến dist/main-stdio.js

Tùy chọn gỡ lỗi:

  • --inspect=9229 - Bắt đầu trình gỡ lỗi ngay lập tức, không chặn (khuyến nghị)
  • --inspect-brk=9229 - Tạm dừng thực thi cho đến khi trình gỡ lỗi gắn vào (để gỡ lỗi các vấn đề khởi động)

Bước 2: Khởi động lại Claude Desktop

Sau khi lưu cấu hình, khởi động lại Claude Desktop. Máy chủ MCP bây giờ sẽ chạy với gỡ lỗi được bật trên cổng 9229.

Bước 3: Gắn Trình gỡ lỗi từ IDE của Bạn

WebStorm
  1. Đi tới Run → Edit Configurations
  2. Nhấp nút + và chọn Attach to Node.js/Chrome
  3. Cấu hình:
    • Name: Attach to Anki MCP (Claude Desktop)
    • Host: localhost
    • Port: 9229
    • Attach to: Node.js < 8 hoặc Chrome or Node.js > 6.3 (tùy thuộc vào phiên bản WebStorm)
  4. Nhấp OK
  5. Nhấp Debug (Shift+F9) để gắn
VS Code
  1. Thêm vào .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. Mở bảng Debug (Ctrl+Shift+D / Cmd+Shift+D)
  2. Chọn Attach to Anki MCP (Claude Desktop)
  3. Nhấn F5 để gắn

Bước 4: Gỡ lỗi trong Thời gian Thực

Sau khi được gắn, bạn có thể:

  • Đặt điểm dừng trong các tệp nguồn TypeScript của bạn (ví dụ: src/mcp/primitives/essential/tools/create-model.tool.ts)
  • Sử dụng Claude Desktop bình thường - các điểm dừng sẽ được kích hoạt khi các công cụ được gọi
  • Bước qua thực thi mã
  • Kiểm tra biến và ngăn xếp cuộc gọi
  • Sử dụng bảng điều khiển gỡ lỗi

Ví dụ: Đặt một điểm dừng trong create-model.tool.ts tại dòng 119, sau đó yêu cầu Claude tạo một mô hình mới. Trình gỡ lỗi sẽ tạm dừng tại điểm dừng của bạn!

Lưu ý: Trình gỡ lỗi vẫn được gắn miễn là Claude Desktop đang chạy. Bạn có thể gỡ/gắn lại bất cứ lúc nào mà không cần khởi động lại Claude Desktop.

Lệnh Xây dựng

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

Kiểm thử Gói NPM (Cục bộ)

Kiểm thử gói npm cục bộ trước khi xuất bản:

# 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

Cách thức hoạt động:

  • npm pack tạo một tệp .tgz giống hệt với những gì npm publish sẽ tạo
  • Cài đặt từ .tgz mô phỏng những gì người dùng nhận được từ npm install -g ankimcp
  • Điều này cho phép bạn kiểm thử toàn bộ trải nghiệm người dùng trước khi xuất bản lên npm

Lệnh Kiểm thử

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)

Phạm vi Kiểm thử

Dự án duy trì ngưỡng phạm vi tối thiểu 70% cho:

  • Nhánh
  • Hàm
  • Dòng
  • Câu lệnh

Báo cáo phạm vi được tạo trong thư mục coverage/.

Phiên bản

Dự án này tuân theo Semantic Versioning với cách tiếp cận phát triển tiền 1.0:

  • 0.x.x - Phiên bản Beta/Phát triển (giai đoạn hiện tại)

    • 0.1.x - Sửa lỗi và bản vá
    • 0.2.0+ - Tính năng mới hoặc cải tiến nhỏ
    • Thay đổi phá vỡ được chấp nhận trong các phiên bản 0.x

  • 1.0.0 - Bản phát hành ổn định đầu tiên

    • Sẽ được phát hành khi API ổn định và được kiểm thử
    • Các thay đổi phá vỡ sẽ yêu cầu tăng phiên bản chính (2.0.0, v.v.)

Trạng thái Hiện tại: 0.22.0 - Đang phát triển beta tích cực. Các tính năng gần đây bao gồm phân tích đánh giá toàn bộ bộ sưu tập (review_stats hiện tổng hợp trên tất cả các bộ thẻ khi deck bị bỏ qua), quản lý trường mô hình (addModelField, removeModelField, renameModelField, repositionModelField), tạo ghi chú hàng loạt (addNotes), đường hầm ngrok tích hợp (cờ --ngrok), quản lý tệp phương tiện, quản lý mô hình/mẫu và thống kê bộ thẻ toàn diện. API có thể thay đổi dựa trên phản hồi và kiểm thử.

Tiến hóa đặc tả MCPB

Dự án này nhắm mục tiêu đặc tả gói MCPB của Anthropic, vẫn đang phát triển. Chúng tôi theo dõi đặc tả tại https://github.com/modelcontextprotocol/mcpb và có thể đưa ra các thay đổi phá vỡ để tuân thủ. Các thay đổi phá vỡ được cho phép theo sơ đồ phiên bản 0.x.x.

Dự án Tương tự

Nếu bạn đang khám phá các tích hợp Anki MCP, đây là các dự án khác trong không gian này:

scorzeth/anki-mcp-server

  • Trạng thái: Có vẻ như bị bỏ rơi (không có cập nhật gần đây)
  • Triển khai sớm tích hợp Anki MCP

nailuoGG/anki-mcp-server

  • Cách tiếp cận: Triển khai nhẹ, tệp đơn
  • Kiến trúc: Cấu trúc mã thủ tục với tất cả các công cụ trong một tệp
  • Phù hợp cho: Các trường hợp sử dụng đơn giản, phụ thuộc tối thiểu Tại sao dự án này khác biệt:
  • Kiến trúc cấp doanh nghiệp: Xây dựng trên NestJS với dependency injection
  • Thiết kế mô-đun: Mỗi công cụ là một lớp riêng biệt với sự phân tách rõ ràng các mối quan tâm
  • Khả năng bảo trì: Dễ dàng mở rộng với các tính năng mới mà không cần chạm vào mã hiện có
  • Kiểm thử: Bộ kiểm thử toàn diện với yêu cầu độ phủ 70%
  • An toàn kiểu: TypeScript nghiêm ngặt với xác thực Zod
  • Xử lý lỗi: Xử lý lỗi mạnh mẽ với phản hồi hữu ích cho người dùng
  • Sẵn sàng cho sản xuất: Ghi nhật ký, báo cáo tiến độ và hỗ trợ gói MCPB đúng cách
  • Khả năng mở rộng: Có thể dễ dàng phát triển từ các công cụ cơ bản đến các quy trình làm việc phức tạp

Trường hợp sử dụng: Nếu bạn cần một nền tảng vững chắc để xây dựng các tích hợp Anki nâng cao hoặc có kế hoạch mở rộng đáng kể chức năng, cách tiếp cận kiến trúc của dự án này giúp việc bảo trì và mở rộng theo thời gian trở nên dễ dàng hơn.

Liên kết hữu ích

Giấy phép & Ghi công

Dự án này được cấp phép theo Giấy phép MIT — xem LICENSE để biết toàn văn.

Bản quyền © 2026 Anatoly Tarnavsky.

Ghi công của bên thứ ba

  • Anki® là nhãn hiệu đã đăng ký của Ankitects Pty Ltd. Dự án này là một công cụ không chính thức của bên thứ ba và không liên kết, được xác nhận hoặc tài trợ bởi Ankitects Pty Ltd. Logo Anki được sử dụng theo giấy phép thay thế để tham chiếu Anki với liên kết đến https://apps.ankiweb.net. Đối với ứng dụng Anki chính thức, hãy truy cập https://apps.ankiweb.net.

  • Model Context Protocol (MCP) là một tiêu chuẩn mở của Anthropic. Logo MCP đến từ kho lưu trữ tài liệu MCP chính thức và được sử dụng theo Giấy phép MIT. Để biết thêm thông tin về MCP, hãy truy cập https://modelcontextprotocol.io.

  • Đây là một dự án độc lập kết nối các công nghệ Anki và MCP. Tất cả các nhãn hiệu, nhãn hiệu dịch vụ, tên thương mại, tên sản phẩm và logo đều là tài sản của chủ sở hữu tương ứng.