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

539

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

Ôn lại các thẻ đến hạn — Yêu cầu trợ lý của bạn kéo các thẻ đến hạn từ một bộ bài cụ thể và kiểm tra bạn qua chúng bằng get_due_cards và present_card.
Đánh giá hiệu suất thẻ — Cho trợ lý ghi lại chất lượng câu trả lời của bạn (Again, Hard, Good, Easy) để lên lịch ôn tập lại qua rate_card.
Tạo flashcard tùy chỉnh — Hướng dẫn trợ lý xây dựng các loại ghi chú mới với trường tùy chỉnh và kiểu RTL bằng createModel và updateModelStyling, sau đó thêm hàng loạt ghi chú bằng addNotes.
Quản lý nội dung ghi chú — Tìm kiếm ghi chú bằng cú pháp truy vấn Anki (deck:, tag:, is:due) qua findNotes, sau đó cập nhật các trường của chúng bằng updateNoteFields.
Nhập phương tiện vào thẻ — Yêu cầu trợ lý tải lên một hình ảnh từ đường dẫn cục bộ hoặc URL bằng storeMediaFile và chèn nó vào trường của một ghi chú đã chọn bằng guiSelectedNotes và updateNoteFields.
Tổ chức bộ bài và thẻ — Tạo bộ bài lồng nhau (Parent::Child) bằng createDeck, di chuyển thẻ giữa các bộ bài bằng changeDeck, hoặc tạm ngưng thẻ bằng suspend để bỏ qua chúng trong lúc ôn tập.

Tài liệu

Máy chủ Anki MCP

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

[!QUAN TRỌNG] Ưu tiên sử dụng tiện ích bổ sung AnkiMCP cho hầu hết các thiết lập.

Tiện ích bổ sung (GitHub) chạy máy chủ MCP trực tiếp bên trong Anki. Không cần cài đặt Node.js, không cần cấu hình AnkiConnect, không cần giữ một tiến trình riêng biệt chạy nền: cài đặt nó bằng mã 124672614, khởi động lại Anki, và máy chủ sẽ sẵn sàng mỗi khi Anki mở. Nó hỗ trợ truy cập HTTP cục bộ và truy cập từ xa thông qua một đường hầm tích hợp sẵn.

Kho lưu trữ này là lựa chọn phù hợp khi bạn đặc biệt cần:

Giao thức STDIO — Claude Desktop, Claude Code, Cursor, hoặc bất kỳ ứng dụng khách nào khởi chạy máy chủ như một tiến trình con

Gói MCPB — cài đặt .mcpb một cú nhấp chuột cho Claude Desktop

Đối với HTTP, đường hầm, hoặc các ứng dụng khách dựa trên web (claude.ai, ChatGPT), tiện ích bổ sung là lựa chọn đơn giản hơn và được hỗ trợ tốt hơn.

Kho lưu trữ này không bị ngừng phát triển. Nó vẫn được duy trì và phát hành cùng với tiện ích bổ sung như một phần của cùng dự án ankimcp.ai.

Máy chủ Giao thức Ngữ cảnh Mô hình (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.

Biến đổi trải nghiệm Anki của bạn với tương tác ngôn ngữ tự nhiên - như có một gia sư riêng. Trợ lý AI không chỉ trình bày 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 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 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. Nhiều tính năng sắp ra mắt!

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

Để có cá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 hoàn chỉnh với các ví dụ thực tế và trường hợp sử dụng

Xem docs/ để có tài liệu bổ sung, bao gồm hướng dẫn thiết lập người đánh giá và bộ bài Anki mẫu.

Các Trường Hợp Sử Dụng Ví Dụ

Ba lời nhắc đại diện cho thấy các luồng công cụ mà máy chủ này hỗ trợ:

"Giúp tôi ôn tập bộ bài tiếng Tây Ban Nha của tôi." — Trợ lý đề nghị đồng bộ với AnkiWeb (sync), lấy các thẻ đến hạn (get_due_cards với bộ lọc bộ bài), trình bày từng thẻ (present_card) và ghi lại xếp hạng 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 phù hợp với bạn.
"Tạo 10 thẻ từ vựng tiếng Ả Rập với định dạng RTL." — Trợ lý liệt kê các loại ghi chú (modelNames), tạo một 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 các thẻ (addNotes).
"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 đượ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ác Công Cụ Có Sẵn

Máy chủ cung cấp 53 công cụ MCP — 42 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ác Công Cụ Thiết Yếu

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

sync - Đồng bộ với AnkiWeb để kéo 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ộ bài (bỏ qua câu trả lời trừ khi include_answer: true, mặc định false)
get_cards - Lấy các thẻ với bộ lọc linh hoạt theo trạng thái (đến hạn, mới, đang học, bị treo, bị chôn) và bộ bài (bỏ qua câu trả lời trừ khi include_answer: true, mặc định false)
present_card - Hiển thị một thẻ để ôn tập với mặt câu hỏi/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 cho lần ôn tập tiếp theo
forgetCards - Đặt lại các thẻ về trạng thái mới, loại bỏ lịch trình của chúng mà không ghi lại một lần ôn tập
setDueDate - Lên lịch lại các thẻ để đến hạn trong N ngày ("0", "3-7", "1!"), mà không ghi lại một lần ôn tập
areSuspended - Kiểm tra trạng thái treo cho một hoặc nhiều thẻ mà không thay đổi bất cứ điều gì
suspend - Treo các thẻ để chúng bị bỏ qua trong quá trình ôn tập cho đến khi được bỏ treo
unsuspend - Bỏ treo các thẻ để chúng trở lại ôn tập bình thường

Lưu ý: forgetCards và setDueDate thay đổi lịch trình mà không ghi lại một lần ôn tập, đó là điều phân biệt chúng với rate_card. Hãy sử dụng chúng khi lịch trình của một thẻ sai thay vì câu trả lời: đánh giá một thẻ Again để chôn nó sâu hơn sẽ ghi lại một lần trượt thực sự và giảm hệ số dễ dàng của nó, vĩnh viễn làm sai lệch cả lịch trình tương lai và số liệu thống kê của bạn. forgetCards xóa khoảng thời gian và bắt đầu lại thẻ; setDueDate giữ lịch sử của thẻ và chỉ di chuyển lần ôn tập tiếp theo.

Lưu ý: Nội dung thẻ front/back được hiển thị cho từng thẻ theo mẫu của riêng nó (như Anki hiển thị), vì vậy các thẻ đảo ngược và cloze hiển thị đúng hướng. Văn bản tĩnh được thêm bởi các mẫu thẻ của bạn cũng xuất hiện trong đầu ra.

Quản Lý Bộ Bài

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

Lưu ý: Số liệu thống kê bộ bài có hai loại. Khối counts (và mọi thứ listDecks báo cáo) phản ánh trình duyệt bộ bài của Anki: các thẻ đến hạn hôm nay, giới hạn bởi giới hạn mới/ôn tập hàng ngày của mỗi bộ bài, với các thẻ bị treo và bị chôn bị loại trừ — vì vậy review không phải là "thẻ trưởng thành" và nhóm other chỉ là phần còn lại số học (chủ yếu là các thẻ ôn tập chưa đến hạn hôm nay cộng với các thẻ mới vượt quá giới hạn hàng ngày). Để có tổng số thực theo trạng thái, hãy sử dụng khối states trên deckStats / collection_stats, khối này đếm new, learning, review, suspended và buried thông qua các tìm kiếm Anki, bỏ qua ngày đến hạn và giới hạn hàng ngày.

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ú dùng chung một bộ bài 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ú (các trường, thẻ, loại ghi chú, ID thẻ; CSS đến từ modelStyling)
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ả các thẻ trong bộ sưu tập (sử dụng đầu tiên để tránh trùng lặp)
addTags - Thêm các thẻ phân tách bằng dấu cách vào các ghi chú được chỉ định
removeTags - Xóa các thẻ phân tách bằng dấu cách khỏi các ghi chú được chỉ định
replaceTags - Đổi tên một thẻ trên các ghi chú được chỉ định
clearUnusedTags - Xóa các thẻ mồ côi không được bất kỳ ghi chú nào sử dụng (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 một 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 một 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ý việc 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 các trường cho một loại ghi chú cụ thể
modelStyling - Lấy thông tin định 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 định dạng CSS cho một loại ghi chú hiện có (áp dụng cho tất cả các thẻ của nó)
updateModelTemplates - Cập nhật các 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ả các thẻ của nó)
addModelField - Thêm một trường mới vào một loại ghi chú hiện có (thêm vào cuối hoặc chèn vào một vị trí cụ thể)
removeModelField - Xóa một trường khỏi một loại ghi chú hiện có (xóa nội dung của nó khỏi tất cả các ghi chú; yêu cầu xác nhận rõ ràng)
renameModelField - Đổi tên một trường trong một loại ghi chú hiện có (Anki viết lại các tham chiếu đến tên cũ trong các mẫu thẻ)
repositionModelField - Thay đổi vị trí của một trường trong một 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ộ bài với phân tích chi tiết theo từng bộ bài và số lượng trạng thái thẻ trên toàn bộ sưu tập
review_stats - Phân tích lịch sử ôn tập (các mẫu thời gian, chỉ số ghi nhớ, chuỗi học tập)

Các 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 các quy trình chỉnh sửa/tạo ghi chú và quản lý bộ bài, không phải cho các phiên ôn tập.

guiBrowse - Mở Trình duyệt Thẻ và tìm kiếm các 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 đượ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ộ bài cho một bộ bài cụ thể
guiDeckBrowser - Mở hộp thoại Trình duyệt Bộ bài
guiCurrentCard - Lấy thông tin về thẻ hiện tại trong chế độ ôn tập (bao gồm câu trả lời; báo lỗi ngoài 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 câu 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

Anki với plugin AnkiConnect được cài đặt
Node.js 22.12.0+

Cài Đặt

Có một vài cách để đưa máy chủ lên máy của bạn. Sau khi cài đặt, hãy đến Kết nối một Ứng dụng Khách 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ầu hoặc npx)

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

Cài đặt toàn cầu cho các ứng dụng khách 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 (Được Khuyến Nghị cho Claude Desktop)

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

Tải xuống gói .mcpb mới nhất từ trang Releases
Trong Claude Desktop, cài đặt tiện ích mở rộng:
- Phương pháp 1: Đi tới Cài đặt → Tiện ích mở rộng, sau đó kéo và thả tệp .mcpb
- Phương pháp 2: Đi tới 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
Cấu hình URL AnkiConnect nếu cần (mặc định là http://localhost:8765)
Khởi động lại Claude Desktop

Vậy là xong! Gói này 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: một hướng dẫn từ đầu đến tích hợp với một bộ bài mẫu được điền sẵn nằm trong docs/reviewer-setup.md.

Cài Đặt Từ Mã Nguồn (dành cho phát triển)

For development or advanced usage (chạy bộ kiểm thử yêu cầu Node.js 24.9+ — các script npm test tải các gói NestJS 12 chỉ dành cho ESM qua require(esm), mà Jest chỉ hỗ trợ ở đó; yêu cầu runtime để sử dụng máy chủ vẫn là 22.12.0+):

npm install
npm run build

Kết nối Máy khách AI

Có hai cách để trợ lý AI có thể truy cập 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 máy khách AI (Claude Desktop, Cursor, Cline, Zed, hoặc phiên trình duyệt cục bộ). Sử dụng STDIO cho máy khách MCP trên máy tính để bàn, HTTP cho các công cụ dựa trên 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 truy cập Anki đang chạy trên máy cục bộ của bạn. Sử dụng Tunnel được quản lý (✅ khuyến nghị — có xác thực) hoặc, như một lựa chọn thay thế không xác thực nhẹ hơn, ngrok.

Cục bộ

Máy chủ chạy trên cùng máy tính với máy khách 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à giao thức vận chuyển tiêu chuẩn cho các máy khách MCP trên máy tính để bàn — Claude Desktop, Cursor IDE, Cline, Zed Editor, opencode, và các máy khác. Máy khách 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.

Máy khách đượ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 hỗ trợ AI
Zed Editor - trình soạn thảo mã hiện đại, nhanh
opencode - tác nhân mã hóa AI trên thiết bị đầu cuối
Các máy khách MCP khác hỗ trợ giao thức vận chuyển STDIO

Đối với Claude Desktop, gói MCPB bundle là cách dễ nhất. Đối với các máy khách 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ầu

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

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

opencode sử dụng định dạng riêng — máy chủ nằm dưới mcp, lệnh là một mảng duy nhất, và biến môi trường nằm dưới environment:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "anki-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "enabled": true,
      "environment": {
        "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 như tiện ích mở rộng MCP qua chợ tiện ích mở rộng
opencode: opencode.json trong thư mục gốc dự án của bạn, hoặc ~/.config/opencode/opencode.json toàn cầu

Đối với các tính năng cụ thể của máy khách và khắc phục sự cố, hãy tham khảo tài liệu của máy khách 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 đã 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ộ nói giao thức MCP Streamable HTTP. Đây là giao thức vận chuyển mà công cụ AI dựa trên web nói chuyện khi trỏ đến máy của bạn, và cũng là thứ mà 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ỉ ràng buộc với localhost.

Ràng buộc 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 khai), máy chủ chỉ chấp nhận các tiêu đề Host loopback theo mặc định để bảo vệ chống DNS-rebinding — đặt ALLOWED_HOSTS thành (các) tên máy chủ mà máy khách 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ầu

# 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ừ nguồn (cho 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 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

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 phơi bày Anki cục bộ của bạn ra internet để trợ lý từ xa có thể nói chuyện với nó.

Tunnel (✅ Khuyến nghị)

Đường dẫn từ xa được khuyến nghị — có xác thực & an toàn. Không giống như cổng công khai thô, chế độ tunnel 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 URL.

Chế độ Tunnel cho phép trợ lý AI dựa trên web truy cập Anki cục bộ của bạn mà không cần chạy tunnel của riêng bạn. Máy chủ kết nối ra dịch vụ tunnel 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 tiến trình tunnel riêng, và bạn đăng nhập một lần.

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

Chế độ Tunnel sử dụng OAuth 2.0 Device Authorization Grant. Đăng nhập tự động mở trình duyệt của bạn đến trang phê duyệt với mã đã được nhúng trong URL — không cần gõ gì, chỉ cần phê duyệt. (Nếu trình duyệt không thể mở, thiết bị đầu cuối in URL xác minh và mã để 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

Bắt đầu tunnel:

# 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 không có thông tin xác thực, --tunnel tự động bắt đầu luồng đăng nhập trước, sau đó tiếp tục đến tunnel. 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ủ thất bại nhanh và yêu cầu bạn chạy ankimcp --login trước. Khi đã kết nối, URL tunnel công khai được in; 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ế độ Tunnel:

Biến	Mô tả	Mặc định
`TUNNEL_SERVER_URL`	URL WebSocket máy chủ tunnel (giá trị cờ `--tunnel`/`--login` ghi đè giá trị này)	`wss://tunnel.ankimcp.ai`
`TUNNEL_AUTH_CLIENT_ID`	ID máy khách OAuth cho luồng thiết bị. Nâng cao — chỉ cần khi trỏ đến dịch vụ tunnel/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 suy ra từ TUNNEL_SERVER_URL, vì vậy trỏ --tunnel (hoặc TUNNEL_SERVER_URL) đến một máy chủ khác cũng di chuyển xác thực đến máy chủ đó.

Cách hoạt động: Chế độ Tunnel chạy máy chủ MCP trong tiến trình đằng sau giao thức vận chuyển trong bộ nhớ (TunnelTransport). Giao thức vận chuyển đó sở hữu máy chủ MCP và biến mỗi phần thân yêu cầu được chuyển tiếp thành phản hồi, và TunnelClient cầu nối nó đến dịch vụ tunnel từ xa qua WebSocket — chuyển tiếp 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.

Phiên bản giao thức: Vì tunnel kết nối máy chủ MCP trong tiến trình, chế độ tunnel chỉ phục vụ bản sửa đổi 2025 của giao thức MCP, trong khi chế độ STDIO và HTTP phục vụ cả 2025 và bản sửa đổi mới hơn 2026-07-28. Mọi công cụ hoạt động giống nhau trong cả hai trường hợp — nhưng máy khách chỉ nói 2026-07-28 sẽ bị từ chối qua tunnel với lỗi phiên bản giao thức; chạy chế độ STDIO hoặc HTTP cho máy khách đó.

ngrok (lựa chọn thay thế không xác thực)

Nếu bạn muốn phơi bày chế độ HTTP cục bộ công khai mà không cần tài khoản trên tunnel được quản lý, cờ --ngrok tích hợp sẵn khởi chạy 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

Tuyến đường này không 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 an toàn hơn Tunnel. Ưu tiên Tunnel 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ầu và authtoken.)

Cờ --ngrok khởi chạy ngrok với --host-header=rewrite, vì vậy ngrok viết lại Host thượng nguồn 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 Host loopback (xem bảo vệ chống DNS-rebinding) mà không cần bạn phải thêm tên miền *.ngrok công khai vào ALLOWED_HOSTS. Nếu thay vào đó bạn chạy ngrok thủ công, hãy sử dụng cùng cờ — ngrok http --host-header=rewrite 3000 — nếu không ngrok chuyển tiếp tên máy chủ ngrok công khai như Host và máy chủ 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 <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 content changes and rescheduling; rating, suspend and sync still work)
  --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 (hoặc READ_ONLY=true) chặn các thay đổi đối với nội dung ghi chú, bộ bài, thẻ, phương tiện và loại ghi chú, và lên lịch lại thủ công các thẻ. Khi được bật:

Tất cả các thao tác đọc hoạt động bình thường (duyệt bộ bài, xem thẻ, tìm kiếm ghi chú)
Các thay đổi này vẫn được phép: đánh giá thẻ trong quá trình ôn tập (rate_card), tạm ngưng/bỏ tạm ngưng thẻ (suspend, unsuspend), đồng bộ với AnkiWeb (sync), và các công cụ GUI điều hướng cửa sổ Anki (guiBrowse, guiDeckOverview, …)
Các sửa đổi nội dung bị chặn (addNote, deleteNotes, createDeck, updateNoteFields, v.v.); createDeck cho một bộ bài đã tồn tại vẫn thành công, vì không có gì được ghi
Lên lịch lại thủ công bị chặn: forgetCards (đặt lại thành mới) và setDueDate
guiUndo bị chặn, vì hoàn tác có thể hoàn nguyên một thay đổi đối với bộ sưu tập
guiAddCards và guiEditNote bị chặn, vì một ghi chú được thêm hoặc lưu trong hộp thoại chúng mở được ghi vào bộ sưu tập
Hữu ích để khám phá dữ liệu Anki mà không có thay đổi vô tình đối với nội dung của 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:

Đi tới: 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 nội dung 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, xem tài liệu MCP chính thức.

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

Biến	Mô tả	Mặc định
`ANKI_CONNECT_URL`	URL AnkiConnect	`http://localhost:8765`
`ANKI_CONNECT_API_VERSION`	Phiên bản API	`6`
`ANKI_CONNECT_API_KEY`	Khóa API nếu được cấu hình trong AnkiConnect	-
`ANKI_CONNECT_TIMEOUT`	Thời gian chờ yêu cầu tính bằng ms	`5000`
`READ_ONLY`	Bật chế độ chỉ đọc (`true` hoặc `1`)	`false`
`PORT`	Chế độ HTTP: cổng để lắng nghe (cờ `--port` được ưu tiên)	`3000`
`HOST`	Chế độ HTTP: địa chỉ để ràng buộc (cờ `--host` được ưu tiên)	`127.0.0.1`
`ALLOWED_HOSTS`	Chế độ HTTP: các giá trị tiêu đề `Host` bổ sung để chấp nhận ngoài loopback (tên máy chủ phân tách bằng dấu phẩy). Bắt buộc khi ràng buộc đến địa chỉ LAN/công khai hoặc chạy sau proxy ngược. Xem Cấu hình Chế độ HTTP.	chỉ loopback
`ALLOWED_ORIGINS`	Chế độ HTTP: danh sách cho phép phân tách bằng dấu phẩy của các mẫu `Origin`/`Referer` trình duyệt (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_URL`	URL WebSocket máy chủ tunnel (chỉ chế độ tunnel)	`wss://tunnel.ankimcp.ai`
`MEDIA_ALLOWED_TYPES`	Cá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_DIR`	Giới hạn nhập đường dẫn tệp vào thư mục này	-
`MEDIA_ALLOWED_HOSTS`	Cho phép các máy chủ mạng riêng cụ thể cho 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ộ bài cụ thể
"tag:important" - Ghi chú có thẻ "important"
"is:due" - Thẻ bài đến hạn ôn tập
"is:new" - Thẻ bài 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" ở trường mặt trước
"flag:1" - Ghi chú có cờ đỏ
"prop:due<=2" - Thẻ bài đến hạn trong vòng 2 ngày
"deck:Spanish tag:verb" - Ghi chú bộ bài tiếng Tây Ban Nha có thẻ động từ (AND)
"deck:Spanish OR deck:French" - Ghi chú từ một trong hai bộ bài

Ghi chú quan trọng

Xử lý CSS và HTML

Công cụ notesInfo trả về tên loại ghi chú của từng ghi chú; bản thân CSS đến từ modelStyling
Công cụ updateNoteFields hỗ trợ nội dung HTML trong các trường và giữ nguyên kiểu dáng CSS
Mỗi mô hình ghi chú có kiểu CSS riêng - sử dụng modelStyling để lấy CSS riêng cho từng 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ập nhật đúng cách. Hãy đóng trình duyệt hoặc chuyển sang một 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 nhầm. Xóa một ghi chú sẽ xóa vĩnh viễn TẤT CẢ các thẻ bài 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 lạm dụng thông qua tiêm prompt:

Nhập đường dẫn tệp chỉ giới hạn ở 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 để giới hạn 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), link-local (169.254.x) và các giao thứ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 path traversal (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 path traversal được báo cáo bởi Hideaki Takahashi.

Bảo vệ chống DNS-Rebinding (giao thức 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ị chuyển hướng đến máy chủ cục bộ với Host giả mạo và không có Origin, và truy cập vào 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 sau reverse proxy, hoặc phơi bày một miền tunnel công khai, hãy đặt ALLOWED_HOSTS (danh sách tên máy chủ phân tách bằng dấu phẩy) để cho phép các máy chủ đó. Khi tunnel với ngrok, máy chủ sử dụng --host-header=rewrite, vì vậy upstream 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 telemetry, 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ì. Nó chuyển tiếp các yêu cầu giữa trợ lý AI của bạn và plugin AnkiConnect cục bộ của bạn.
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 chú 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 có. Máy chủ chỉ giao tiếp với URL AnkiConnect bạn cấu hình (mặc định: localhost). Nếu bạn bật đồng bộ AnkiWeb tích hợp của Anki, điều đó xảy ra trực tiếp giữa cài đặt Anki của bạn và AnkiWeb — 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

Để có 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

Các hạn chế quan trọng

Cập nhật ghi chú thất bại khi xem trong trình duyệt

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

Giải pháp: 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, xem tài liệu đầy đủ.

Xử lý 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 tối thiểu được hỗ trợ là Node.js 22.12.0. Node.js 20 (Iron) đã hết hạn hỗ trợ vào 2026-04-30 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

Các chế độ vận chuyển

Máy chủ này hỗ trợ ba chế độ vận chuyển 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 (Streamable HTTP)

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ế độ Tunnel (Managed WebSocket Tunnel)

Dành cho các trợ lý AI dựa trên web thông qua dịch vụ tunnel AnkiMCP được quản lý, với xác thực tích hợp
Máy chủ MCP chạy trong tiến trình phía sau một bộ vận chuyển trong bộ nhớ; TunnelTransport sở hữu máy chủ MCP và TunnelClient cầu nối nó đến dịch vụ tunnel qua WebSocket
Giao thức: chỉ phục vụ bản sửa đổi MCP 2025 (STDIO và HTTP cũng phục vụ 2026-07-28)
Đ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 nào để 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 cho chỉ 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 hợp loopback tích hợp (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 phân tách bằng dấu phẩy của các mẫu Origin/Referer trình duyệt; 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ị chuyển hướng đến máy chủ với Host giả mạo và không có Origin. Một 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 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 phép; xác thực Host là biện pháp phòng thủ chống 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 được lên kế hoạch).

Phơi bày chế độ HTTP ngoài localhost — nếu bạn liên kết với địa chỉ LAN/công khai hoặc đặt máy chủ sau reverse proxy hoặc miền công khai, 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 sẽ được chấp nhận.

Docker / reverse proxy / miền công khai: 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ủ được công bố của container hoặc Host của proxy, vì vậy hãy đặt ALLOWED_HOSTS cho phù hợp. Một reverse proxy (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 upstream thành localhost. Tích hợp --ngrok tích hợp xử lý việc này tự động (xem bên dưới).

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

# 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ẽ:

Đồng bộ phiên bản từ package.json sang manifest.json
Xóa các tệp .mcpb cũ
Xây dựng dự án TypeScript
Đóng gói dist/ và node_modules/ thành một tệp .mcpb
Chạy mcpb clean để xóa 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 cả ba điểm vào)
Chỉ các dependency sản xuất (node_modules/ - devDependencies bị xóa bởi mcpb clean)
Siêu dữ liệu gói (package.json)
Cấu hình manifest (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, bài kiểm tra và cấu hình phát triển tự động bị loại trừ qua .mcpbignore.

Ghi nhật ký trong Claude Desktop

Khi chạy như một 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 - Thông điệp 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 (thông điệp INFO, ERROR, WARN từ mã máy chủ) đi đến stderr và xuất hiện trong các tệp nhật ký cụ thể của MCP. Claude Desktop xác định tệp nhật ký nào nhận thông điệp nào, nhưng nói chung:

Khởi động ứng dụng và giao tiếp giao thức MCP → Nhật ký cụ thể của MCP
Ghi nhật ký nội bộ máy chủ (pino) → Cả nhật ký cụ thể của MCP và đôi khi 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à đính kèm trình gỡ lỗi từ IDE của bạn (WebStorm, VS Code, v.v.).

Lưu ý cho chế độ HTTP: Khi kiểm tra chế độ HTTP (Streamable HTTP) 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

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

Bước 3: Đính kèm Trình gỡ lỗi từ IDE của bạn

WebStorm

Đi tới Run → Edit Configurations
Thêm cấu hình Attach to Node.js/Chrome mới
Đặt cổng thành 9229
Nhấp Debug để đính kèm

VS Code

Mở bảng Debug (Ctrl+Shift+D / Cmd+Shift+D)
Chọn cấu hình Debug MCP Server (Attach)
Nhấn F5 để đính kèm

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

Sau khi đính kèm, bạn có thể:

Đặt điểm dừng trong các tệp mã nguồn TypeScript của bạn
Bước qua quá trình 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 source maps, 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à đính kèm 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 - Khởi động 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 đính kèm (để 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, hãy khởi động lại Claude Desktop. Máy chủ MCP sẽ chạy với tính năng gỡ lỗi được bật trên cổng 9229.

Bước 3: Đính kèm Trình gỡ lỗi từ IDE của bạn

WebStorm

Đi tới Run → Edit Configurations
Nhấp nút + và chọn Attach to Node.js/Chrome
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)
Nhấp OK
Nhấp Debug (Shift+F9) để đính kèm

VS Code

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

Mở bảng Debug (Ctrl+Shift+D / Cmd+Shift+D)
Chọn Attach to Anki MCP (Claude Desktop)
Nhấn F5 để đính kèm

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

Sau khi đính kèm, bạn có thể:

Đặt điểm dừng trong các tệp mã 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 - điểm dừng sẽ kích hoạt khi các công cụ được gọi
Bước qua quá trình 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 đ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 đính kèm miễn là Claude Desktop đang chạy. Bạn có thể tách/đính kèm 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 hoạt động:

npm pack tạo một tệp .tgz giống hệt 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ử trải nghiệm người dùng đầy đủ 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 Phiên bản Ngữ nghĩa 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à vá lỗi
- 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ử
- 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.27.0 - 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 ôn tập toàn bộ bộ sưu tập (review_stats hiện tổng hợp trên tất cả các bộ bài 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ộ bài toàn diện. API có thể thay đổi dựa trên phản hồi và kiểm thử.

Sự phát triển của đặc tả MCPB

Dự án này nhắm đến đặc tả gói MCPB của Anthropic, vốn 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ể giới thiệu các thay đổi phá vỡ để tuân thủ. Các thay đổi phá vỡ được phép theo sơ đồ phiên bản 0.x.x.

Các 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 lĩnh vực này:

scorzeth/anki-mcp-server

Trạng thái: Có vẻ đã bị bỏ hoang (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ẹ, một tệp duy nhất
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: Được 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ự tách biệt rõ ràng về 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ạm vi 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 sản xuất: Ghi nhật ký phù hợp, báo cáo tiến độ và hỗ trợ gói MCPB
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 chức năng đáng kể, cách tiếp cận kiến trúc của dự án này giúp dễ dàng bảo trì và mở rộng theo thời gian.

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.

Ghi công Bên thứ ba

Anki® là nhãn hiệu đã đăng ký của Ankitects Pty Ltd. Dự án này là công cụ bên thứ ba không chính thức và không liên kết với, được xác nhận bởi, hoặc đượ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.
Giao thức Ngữ cảnh Mô hình (MCP) là một tiêu chuẩn mở của Anthropic. Logo MCP 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ông nghệ Anki và MCP. Tất 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 là tài sản của chủ sở hữu tương ứng.