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

481

Dùng thử MCP nàyĐược tài trợ

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

Xem lại các thẻ đến hạn theo kiểu hội thoại — Yêu cầu trợ lý của bạn kéo các thẻ đến hạn lên bằng get_due_cards, trình bày từng thẻ qua present_card và ghi lại mức đánh giá của bạn bằng rate_card.
Tạo và thêm hàng loạt flashcard — Nhờ trợ lý tạo ghi chú hàng loạt bằng addNotes, tùy chọn xây dựng mô hình tùy chỉnh trước qua createModel và updateModelStyling.
Tìm kiếm và chỉnh sửa ghi chú hiện có — Sử dụng findNotes với cú pháp truy vấn Anki, xem chi tiết qua notesInfo và cập nhật các trường bằng updateNoteFields.
Quản lý bộ bài và lịch trình — Tạo bộ bài bằng createDeck, di chuyển thẻ qua changeDeck hoặc lên lịch lại thẻ bằng setDueDate và forgetCards.
Nhập phương tiện vào ghi chú — Yêu cầu trợ lý tải lên hình ảnh cục bộ hoặc URL bằng storeMediaFile và nhúng nó vào một trường của ghi chú.
Điều khiển giao diện Anki — Mở trình duyệt hoặc trình soạn thảo bằng guiBrowse và guiEditNote, hoặc lấy ghi chú đang chọn qua guiSelectedNotes.

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

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 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 trải nghiệm Anki của bạn thành 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 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ó 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/ để 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.

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

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ý đồ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 kiểu 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 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 50 công cụ MCP — 39 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ộ 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 (câu trả lời bị ẩn 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ị đình chỉ, bị chôn) và bộ bài (câu trả lời bị ẩn 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 ô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 - Đổi lịch trình 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

Lưu ý: forgetCards và setDueDate thay đổi lịch trình mà không ghi nhật ký ô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ó, làm sai lệch vĩnh viễn cả lịch trình tương lai và 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ị theo từng thẻ từ mẫu riêng của 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 thống kê hàng đợi học tập theo từng bộ bài
deckStats - Lấy 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 tế, 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 (được tạo nếu nó không tồn tại)

Lưu ý: Thống kê bộ bài có hai dạng. 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ị đình chỉ 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 dư 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 theo trạng thái thực sự, 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ú chia sẻ 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ú (trường, thẻ, kiểu 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ả 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, 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 trường cho một loại ghi chú cụ thể
modelStyling - Lấy thông tin kiểu 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 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ó (được thêm vào cuối hoặc chèn tại 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ó (các mẫu thẻ tham chiếu tên cũ phải được cập nhật riêng)
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 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 (mẫu thời gian, chỉ số duy trì, 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 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
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áy 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 với bất kỳ máy khách MCP nào khởi chạy trực tiếp.

Cài đặt toàn cầu cho các máy 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 Bản phát hành
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: hướng dẫn từ đầu đến tích hợp với bộ bài mẫu được điền sẵn nằm trong docs/reviewer-setup.md.

Cài đặt từ Nguồn (dành cho phát triển)

Dành cho phát triển hoặc sử dụng nâng cao (chạy bộ kiểm thử yêu cầu Node.js 24.9+ — các tập lệnh kiểm thử npm 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 thời gian chạy để 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 một 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 các 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 — một 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ý (✅ được 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 truyền tải tiêu chuẩn cho các máy khách MCP trên máy tính để bàn cục bộ — Claude Desktop, Cursor IDE, Cline, Zed Editor 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. Các máy khách được hỗ trợ:

Claude Desktop
Cursor IDE - trình soạn thảo mã nguồn hỗ trợ AI
Cline - tiện ích mở rộng VS Code hỗ trợ AI
Zed Editor - trình soạn thảo mã nguồn hiện đại, nhanh
Các máy khách MCP khác hỗ trợ giao thức 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, hãy cấu hình gói npm với cờ --stdio.

Cấu hình - Chọn một trong các 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 như tiện ích mở rộng MCP thông qua chợ tiện ích mở rộng

Đối với các tính năng cụ thể của máy khách và cách khắc phục sự cố, hãy tham khảo tài liệu của máy khách MCP. Xem thêm Kết nối với Claude Desktop để có 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 MCP Streamable HTTP. Đây là phương thức truyền tải mà công cụ AI dựa trên web sử dụng khi trỏ đến máy của bạn và cũng là thứ mà các tùy chọn Remote hiển thị với thế giới bên ngoài. Tự nó, chế độ HTTP chỉ liên kết với localhost.

Liên kết ngoài localhost? Nếu bạn truyền --host 0.0.0.0 (hoặc chạy sau proxy ngược/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 — hãy đặ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 trong các 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 (dành 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 từ AI lưu trữ trên đám mây, hãy sử dụng một trong các tùy chọn Remote bên dưới.

Remote

AI 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 hiển thị Anki cục bộ của bạn với internet để trợ lý từ xa có thể giao tiếp với nó.

Tunnel (✅ Khuyến nghị)

Đường dẫn từ xa được khuyến nghị — xác thực và 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 được 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 ngoài đến 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 quy trình tunnel riêng và bạn chỉ cầ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 sẽ 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 nhập gì, chỉ cần phê duyệt. (Nếu trình duyệt không thể mở, thiết bị đầu cuối sẽ 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 nào tồn tại, --tunnel sẽ 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ủ sẽ 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 sẽ đượ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 của 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ữ.	(được 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 chuyển xác thực đến máy chủ đó.

Cách hoạt động: Chế độ Tunnel chạy máy chủ MCP trong quy trình phía sau một phương thức truyền tải trong bộ nhớ (TunnelTransport). Phương thức truyền tải đó 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 một phản hồi, và TunnelClient kết nối nó với dịch vụ tunnel 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.

Phiên bản giao thức: Vì tunnel kết nối máy chủ MCP trong quy trình, chế độ tunnel chỉ phục vụ phiên bản 2025 của giao thức MCP, trong khi chế độ STDIO và HTTP phục vụ cả phiên bản 2025 và phiên bản 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; hãy chạy chế độ STDIO hoặc HTTP cho máy khách đó.

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

Nếu bạn muốn hiển thị 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 sẽ khởi chạy một quy 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. Hãy ư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ục 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 miền *.ngrok công khai vào ALLOWED_HOSTS. Nếu 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 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 <number>            Port to listen on (HTTP mode; default: 3000, or PORT env var)
  -h, --host <address>           Host to bind to (HTTP mode; default: 127.0.0.1, or HOST env var)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765, or ANKI_CONNECT_URL env var)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks all write operations)
  --help                         Show help message

Usage with npx (no installation needed):
  npx @ankimcp/anki-mcp-server                        # HTTP mode
  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
  npx @ankimcp/anki-mcp-server --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

Usage with global installation:
  npm install -g @ankimcp/anki-mcp-server             # Install once
  ankimcp                                             # HTTP mode
  ankimcp --port 8080                                 # Custom port
  ankimcp --stdio                                     # STDIO mode
  ankimcp --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

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

Cờ --read-only ngă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ộ bài, xem thẻ, tìm kiếm ghi chú)
Các thao tác xem xét được phép (đồng bộ hóa, answerCards, tạm ngưng/bỏ tạm ngưng)
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ó rủi ro 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:

Đ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, hãy 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ỉ để liên kết (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 liên kết đế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ác mẫu `Origin`/`Referer` của 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 của máy chủ tunnel (chỉ chế độ tunnel)	`wss://tunnel.ankimcp.ai`
`MEDIA_ALLOWED_TYPES`	Các loại MIME bổ sung được phép cho việc 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 việc 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 việc 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ụ về 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ẻ đến hạn xem xét
"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ộ bài tiếng Tây Ban Nha có thẻ verb (AND)
"deck:Spanish OR deck:French" - Ghi chú từ một trong hai bộ bài

Lưu ý Quan trọng

Xử lý CSS và HTML

Công cụ notesInfo trả về thông tin định dạng CSS để nhận biết hiển thị đúng cách
Công cụ updateNoteFields hỗ trợ nội dung HTML trong các trường và bảo toàn định dạng CSS
Mỗi mô hình ghi chú có định 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 Anki trong khi cập nhật, nếu không các trường sẽ không cập nhật đúng cách. Đó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 Xóa

Công cụ deleteNotes yêu cầu xác nhận rõ ràng (confirmDeletion: true) để ngăn việc xóa vô tình. 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 và URL Phương tiện

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 sử dụng sai 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 việc 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 lược đồ không phải HTTP(S) 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 (phương thức 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 tấn công 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, rồi 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 đến 0.0.0.0, chạy sau một reverse proxy, hoặc mở một tên 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 dùng 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 dữ liệu telemetry, phân tích hoặc dữ liệu sử dụng.

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 flashcard vẫn nằm trong cài đặt Anki trên thiết bị của 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ế từ AnkiConnect phía trên.

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 ngày 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)
Dev: 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 - Danh sách giá trị tiêu đề Host bổ sung phân tách bằng dấu phẩy để chấp nhận ngoài tậ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 phân tách bằng dấu phẩy các mẫu Origin/Referer của 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 log (mặc định: info)

Bảo mật:

Xác thực tiêu đề Host (bảo vệ 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 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 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 phép; xác thực Host là biện pháp phòng thủ chống rebinding.
Liên kết đến 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).

Mở chế độ HTTP ra ngoài localhost — nếu bạn liên kết đến địa chỉ LAN/công khai hoặc đặt máy chủ sau reverse proxy hoặc tên 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-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 đến 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 / tên 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 xuất bản của container hoặc Host của proxy, vì vậy hãy đặt ALLOWED_HOSTS tương ứng. 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/ vào 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 log trong Claude Desktop

Khi chạy như một tiện ích mở rộng MCPB trong Claude Desktop, các log được ghi vào:

Vị trí log: ~/Library/Logs/Claude/ (macOS)

Các log được chia thành nhiều tệp:

main.log - Log ứ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 - Log MCP kết hợp từ tất cả các máy chủ

Lưu ý: Đầu ra logger 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 log cụ thể của MCP. Claude Desktop xác định tệp log 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 → log cụ thể của MCP
Ghi log nội bộ máy chủ (pino) → Cả log cụ thể của MCP và đôi khi main.log

Để xem log 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

Đ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: Đính kèm trình gỡ lỗi từ IDE của bạn

WebStorm

Đi đến 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

Khi đã đính kèm, bạn có thể:

Đặt điểm dừng trong các tệp 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 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 đến 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 gắn vào, bạn có thể:

Đặt điểm dừng (breakpoint) 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ẽ kích hoạt khi các công cụ được gọi
Bước qua từng bước thực thi mã
Kiểm tra các 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 gắn miễn là Claude Desktop đang chạy. Bạn có thể tách/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 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ử 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 (Branches)
Hàm (Functions)
Dòng (Lines)
Câu lệnh (Statements)

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à bản vá
- 0.2.0+ — Tính năng mới hoặc cải tiến nhỏ
- Các 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 số phiên bản chính (2.0.0, v.v.)

Trạng thái hiện tại: 0.22.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 trên 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 hướng tới đặ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: Nhẹ, triển khai 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

Lý do 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 việc bảo trì và mở rộng theo thời gian dễ dàng hơn.

Liên Kết Hữu Ích

Giấy phép & Ghi nhận

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

Ghi nhận 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.