Anki MCP

Anki MCP Server

Beta - โปรเจกต์นี้อยู่ระหว่างการพัฒนา API และฟีเจอร์อาจมีการเปลี่ยนแปลง

เซิร์ฟเวอร์ Model Context Protocol (MCP) ที่ช่วยให้ผู้ช่วย AI สามารถโต้ตอบกับ Anki แอปพลิเคชันแฟลชการ์ดแบบทบทวนตามช่วงเวลาได้

เปลี่ยนประสบการณ์ Anki ของคุณด้วยการโต้ตอบด้วยภาษาธรรมชาติ - เปรียบเสมือนมีติวเตอร์ส่วนตัว ผู้ช่วย AI ไม่เพียงแค่แสดงคำถามและคำตอบ แต่มันสามารถอธิบายแนวคิด ทำให้กระบวนการเรียนรู้มีความน่าสนใจและเป็นธรรมชาติมากขึ้น ให้บริบท และปรับให้เข้ากับสไตล์การเรียนรู้ของคุณ มันสามารถสร้างและแก้ไขโน้ตได้ทันที เปลี่ยนเซสชันการเรียนของคุณให้เป็นบทสนทนาที่มีชีวิตชีวา ฟีเจอร์เพิ่มเติมกำลังจะมาเร็วๆ นี้!

ตัวอย่างและบทช่วยสอน

สำหรับคำแนะนำที่ครอบคลุม ตัวอย่างการใช้งานจริง และบทช่วยสอนแบบทีละขั้นตอนในการใช้เซิร์ฟเวอร์ MCP นี้กับ Claude Desktop โปรดเยี่ยมชม:

ankimcp.ai - เอกสารฉบับสมบูรณ์พร้อมตัวอย่างการใช้งานจริงและกรณีการใช้งาน

ดู docs/ สำหรับเอกสารเสริม รวมถึง คู่มือการตั้งค่าผู้ตรวจทาน และสำรับ Anki ตัวอย่าง

ตัวอย่างกรณีการใช้งาน

พรอมต์ตัวอย่างสามรายการที่แสดงขั้นตอนเครื่องมือที่เซิร์ฟเวอร์นี้เปิดใช้งาน:

1. "ช่วยฉันทบทวนสำรับภาษาสเปนหน่อย" — ผู้ช่วยซิงค์กับ AnkiWeb (sync) ดึงการ์ดที่ถึงกำหนด (get_due_cards พร้อมตัวกรองสำรับ) แสดงการ์ดแต่ละใบ (present_card) และบันทึกคะแนนของคุณ (rate_card) บทสนทนาการเรียนที่เป็นธรรมชาติพร้อมคำอธิบายที่ปรับให้เหมาะกับคุณ

2. "สร้างการ์ดคำศัพท์ภาษาอาหรับ 10 ใบพร้อมการจัดรูปแบบจากขวาไปซ้าย" — ผู้ช่วยแสดงรายการประเภทโน้ต (modelNames) สร้างโมเดล RTL แบบกำหนดเองหากจำเป็น (createModel + updateModelStyling สำหรับ CSS จากขวาไปซ้าย) จากนั้นสร้างการ์ดเป็นชุด (addNotes)

3. "นำเข้ารูปภาพนี้จากโฟลเดอร์ Downloads ของฉันไปไว้ด้านหน้าของโน้ตที่เลือก" — ผู้ช่วยอัปโหลดไฟล์ในเครื่อง (storeMediaFile พร้อมพาธไฟล์) อ่านโน้ตที่เลือกอยู่ในปัจจุบันจากเบราว์เซอร์ (guiSelectedNotes + notesInfo) และอัปเดตฟิลด์ด้านหน้าด้วยแท็ก <img> (updateNoteFields)

เครื่องมือที่พร้อมใช้งาน

เซิร์ฟเวอร์มีเครื่องมือ MCP 42 รายการ — เครื่องมือจำเป็น 31 รายการสำหรับการดำเนินการ Anki ทั่วไป และเครื่องมือ GUI 11 รายการที่ขับเคลื่อนอินเทอร์เฟซเดสก์ท็อป Anki สำหรับเวิร์กโฟลว์การแก้ไข/สร้างโน้ต

เครื่องมือจำเป็น

การทบทวนและการเรียน

• sync - ซิงค์กับ AnkiWeb เพื่อดึงข้อมูลล่าสุดและส่งการเปลี่ยนแปลง
• get_due_cards - รับการ์ดที่ถึงกำหนดทบทวน สามารถกรองตามสำรับได้
• get_cards - รับการ์ดพร้อมการกรองที่ยืดหยุ่นตามสถานะ (ถึงกำหนด, ใหม่, กำลังเรียน, ถูกระงับ, ถูกฝัง) และสำรับ
• present_card - แสดงการ์ดเพื่อทบทวนพร้อมด้านคำถาม/ด้านหน้า
• rate_card - ให้คะแนนประสิทธิภาพการ์ด (อีกครั้ง, ยาก, ดี, ง่าย) และจัดตารางการทบทวนครั้งต่อไป

หมายเหตุ: เนื้อหาการ์ด front/back ถูกแสดงผลต่อการ์ดจากเทมเพลตของมันเอง (ตามที่ Anki แสดง) ดังนั้นการ์ดแบบกลับด้านและแบบเติมคำจะแสดงทิศทางที่ถูกต้อง ข้อความคงที่ที่เพิ่มโดยเทมเพลตการ์ดของคุณจะปรากฏในผลลัพธ์ด้วยเช่นกัน

การจัดการสำรับ

• listDecks - แสดงรายการสำรับทั้งหมด สามารถเลือกดูสถิติจำนวนการ์ดต่อสำรับได้
• deckStats - รับสถิติที่ครอบคลุมสำหรับสำรับเดียว (จำนวน, การกระจายความง่าย/ช่วงเวลา)
• createDeck - สร้างสำรับเปล่าใหม่ (รองรับ Parent::Child, สูงสุด 2 ระดับ)
• changeDeck - ย้ายการ์ดไปยังสำรับอื่น (สร้างหากยังไม่มี)

การจัดการโน้ต

• addNote - สร้างโน้ตเดี่ยวพร้อมฟิลด์และแท็กที่ระบุ
• addNotes - สร้างโน้ตสูงสุด 100 รายการเป็นชุดที่ใช้สำรับและโมเดลร่วมกัน (รองรับความสำเร็จบางส่วน)
• findNotes - ค้นหาโน้ตโดยใช้ไวยากรณ์การค้นหาของ Anki (deck:, tag:, is:due, ฯลฯ)
• notesInfo - รับข้อมูลโดยละเอียดเกี่ยวกับโน้ต (ฟิลด์, แท็ก, การจัดรูปแบบ CSS)
• updateNoteFields - อัปเดตฟิลด์โน้ตที่มีอยู่ (รับรู้ CSS, รองรับเนื้อหา HTML)
• deleteNotes - ลบโน้ตและการ์ดที่เกี่ยวข้องทั้งหมด (ทำลายข้อมูล, ต้องมีการยืนยัน)

การจัดการแท็ก

• getTags - รับแท็กทั้งหมดในคอลเลกชัน (ใช้ก่อนเพื่อหลีกเลี่ยงการซ้ำซ้อน)
• addTags - เพิ่มแท็กที่คั่นด้วยช่องว่างให้กับโน้ตที่ระบุ
• removeTags - ลบแท็กที่คั่นด้วยช่องว่างออกจากโน้ตที่ระบุ
• replaceTags - เปลี่ยนชื่อแท็กในโน้ตที่ระบุ
• clearUnusedTags - ลบแท็กที่ไม่มีโน้ตใดใช้อีกต่อไป (ทำลายข้อมูล)

การจัดการสื่อ

• getMediaFilesNames - แสดงรายการไฟล์สื่อใน collection.media สามารถกรองตามรูปแบบได้
• retrieveMediaFile - ดาวน์โหลดไฟล์สื่อเป็นเนื้อหา base64
• storeMediaFile - อัปโหลดสื่อจากข้อมูล base64, พาธไฟล์แบบสัมบูรณ์, หรือ URL
• deleteMediaFile - ลบไฟล์สื่อออกจาก collection.media (ทำลายข้อมูล)

💡 แนวทางปฏิบัติที่ดีที่สุดสำหรับรูปภาพ:

• ✅ ใช้พาธไฟล์ (เช่น /Users/you/image.png) - รวดเร็วและมีประสิทธิภาพ
• ✅ ใช้ URL (เช่น https://example.com/image.jpg) - ดาวน์โหลดโดยตรง
• ❌ หลีกเลี่ยง base64 - ช้ามากและไม่มีประสิทธิภาพด้านโทเค็น

เพียงบอก Claude ว่ารูปภาพอยู่ที่ไหน แล้วมันจะจัดการอัปโหลดให้โดยอัตโนมัติโดยใช้วิธีที่มีประสิทธิภาพสูงสุด

การจัดการโมเดล/เทมเพลต

• modelNames - แสดงรายการประเภทโน้ต/โมเดลทั้งหมดที่มี
• modelFieldNames - รับชื่อฟิลด์สำหรับประเภทโน้ตที่ระบุ
• modelStyling - รับข้อมูลการจัดรูปแบบ CSS สำหรับประเภทโน้ต
• modelTemplates - รับเทมเพลตการ์ด (HTML ด้านหน้าและด้านหลัง) สำหรับประเภทโน้ต
• createModel - สร้างประเภทโน้ตใหม่พร้อมฟิลด์ที่กำหนดเอง, เทมเพลตการ์ด, และ CSS (เช่น โมเดล RTL)
• updateModelStyling - อัปเดตการจัดรูปแบบ CSS สำหรับประเภทโน้ตที่มีอยู่ (มีผลกับการ์ดทั้งหมดของมัน)
• updateModelTemplates - อัปเดตเทมเพลตการ์ด (HTML ด้านหน้าและด้านหลัง) สำหรับประเภทโน้ตที่มีอยู่ (มีผลกับการ์ดทั้งหมดของมัน)
• addModelField - เพิ่มฟิลด์ใหม่ให้กับประเภทโน้ตที่มีอยู่ (ต่อท้ายหรือแทรกที่ตำแหน่งเฉพาะ)
• removeModelField - ลบฟิลด์ออกจากประเภทโน้ตที่มีอยู่ (ลบเนื้อหาออกจากโน้ตทั้งหมด; ต้องมีการยืนยันอย่างชัดเจน)
• renameModelField - เปลี่ยนชื่อฟิลด์ในประเภทโน้ตที่มีอยู่ (ต้องอัปเดตเทมเพลตการ์ดที่อ้างอิงชื่อเก่าแยกต่างหาก)
• repositionModelField - เปลี่ยนตำแหน่งของฟิลด์ภายในประเภทโน้ตที่มีอยู่

สถิติ

• collection_stats - สถิติรวมในทุกสำรับพร้อมการแจกแจงรายสำรับ
• review_stats - การวิเคราะห์ประวัติการทบทวน (รูปแบบตามเวลา, เมตริกการจดจำ, สถิติการเรียนต่อเนื่อง)

เครื่องมือ GUI

เครื่องมือที่ขับเคลื่อนอินเทอร์เฟซเดสก์ท็อป Anki มีไว้สำหรับเวิร์กโฟลว์การแก้ไข/สร้างโน้ตและการจัดการสำรับ ไม่ใช่ สำหรับเซสชันการทบทวน

• guiBrowse - เปิดตัวเรียกดูการ์ดและค้นหาการ์ด
• guiSelectCard - เลือกการ์ดที่ระบุในตัวเรียกดูการ์ด
• guiSelectedNotes - รับ ID ของโน้ตที่เลือกอยู่ในปัจจุบันในตัวเรียกดูการ์ด
• guiAddCards - เปิดกล่องโต้ตอบเพิ่มการ์ดพร้อมรายละเอียดโน้ตที่ตั้งไว้ล่วงหน้า
• guiEditNote - เปิดตัวแก้ไขโน้ตสำหรับโน้ตที่ระบุ
• guiDeckOverview - เปิดกล่องโต้ตอบภาพรวมสำรับสำหรับสำรับที่ระบุ
• guiDeckBrowser - เปิดกล่องโต้ตอบตัวเรียกดูสำรับ
• guiCurrentCard - รับข้อมูลเกี่ยวกับการ์ดปัจจุบันในโหมดทบทวน
• guiShowQuestion - แสดงด้านคำถามของการ์ดปัจจุบัน
• guiShowAnswer - แสดงด้านคำตอบของการ์ดปัจจุบัน
• guiUndo - เลิกทำการกระทำล่าสุดใน Anki

ข้อกำหนดเบื้องต้น

• Anki พร้อมปลั๊กอิน AnkiConnect ที่ติดตั้งแล้ว
• Node.js 22.12.0+

การติดตั้ง

มีหลายวิธีในการนำเซิร์ฟเวอร์ไปไว้บนเครื่องของคุณ เมื่อติดตั้งแล้ว ให้ไปที่ การเชื่อมต่อไคลเอนต์ AI เพื่อเชื่อมต่อกับผู้ช่วย AI ของคุณ — ทั้งในเครื่องหรือระยะไกล

npm (global หรือ npx)

วิธีทั่วไปในการติดตั้งเซิร์ฟเวอร์ เหมาะสำหรับไคลเอนต์ MCP ใดๆ ที่เรียกใช้งานโดยตรง

ติดตั้งแบบ global สำหรับไคลเอนต์ที่รันคำสั่ง ankimcp:

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

หรือรันตามต้องการโดยไม่ต้องติดตั้ง:

npx @ankimcp/anki-mcp-server

MCPB Bundle (แนะนำสำหรับ Claude Desktop)

วิธีที่ง่ายที่สุดในการติดตั้งเซิร์ฟเวอร์ MCP นี้สำหรับ Claude Desktop:

1. ดาวน์โหลด .mcpb bundle ล่าสุดจากหน้า Releases
2. ใน Claude Desktop ติดตั้งส่วนขยาย:
   • วิธีที่ 1: ไปที่ Settings → Extensions จากนั้นลากและวางไฟล์ .mcpb
   • วิธีที่ 2: ไปที่ Settings → Developer → Extensions → Install Extension จากนั้นเลือกไฟล์ .mcpb
3. กำหนดค่า URL ของ AnkiConnect หากจำเป็น (ค่าเริ่มต้นคือ http://localhost:8765)
4. รีสตาร์ท Claude Desktop

เท่านี้ก็เรียบร้อย! Bundle ประกอบด้วยทุกสิ่งที่จำเป็นในการรันเซิร์ฟเวอร์ในเครื่อง

สำหรับผู้ตรวจสอบ Anthropic MCP Directory: คำแนะนำแบบทีละขั้นตอนตั้งแต่เริ่มต้นจนถึงการผสานรวมพร้อมสำรับตัวอย่างที่เตรียมไว้ล่วงหน้าอยู่ใน docs/reviewer-setup.md

ติดตั้งจากซอร์ส (สำหรับการพัฒนา)

สำหรับการพัฒนาหรือการใช้งานขั้นสูง:

npm install
npm run build

การเชื่อมต่อไคลเอนต์ AI

มีสองวิธีที่ผู้ช่วย AI สามารถเข้าถึงเซิร์ฟเวอร์นี้ได้ ขึ้นอยู่กับว่าผู้ช่วยรันอยู่ที่ไหน:

• Local — เซิร์ฟเวอร์รันบนเครื่องเดียวกับไคลเอนต์ AI (Claude Desktop, Cursor, Cline, Zed, หรือเซสชันเบราว์เซอร์ในเครื่อง) ใช้ STDIO สำหรับไคลเอนต์ MCP บนเดสก์ท็อป, HTTP สำหรับเครื่องมือบนเว็บในเครื่อง
• Remote — AI ที่โฮสต์/ระยะไกล (เช่น ChatGPT หรือ Claude.ai บนคลาวด์) จำเป็นต้องเข้าถึง Anki ที่รันอยู่บนเครื่องของคุณ ใช้ Tunnel ที่มีการจัดการ (✅ แนะนำ — มีการรับรองความถูกต้อง) หรือเป็นทางเลือกที่เบากว่าและไม่มีการรับรองความถูกต้องคือ ngrok

Local

เซิร์ฟเวอร์รันบนคอมพิวเตอร์เครื่องเดียวกับไคลเอนต์ AI ของคุณและสื่อสารกับ AnkiConnect บน localhost

STDIO (การผสานรวมในเครื่องหลัก)

STDIO เป็นการขนส่งมาตรฐานสำหรับไคลเอนต์ MCP บนเดสก์ท็อปในเครื่อง — Claude Desktop, Cursor IDE, Cline, Zed Editor, และอื่นๆ ไคลเอนต์เรียกใช้เซิร์ฟเวอร์เป็นกระบวนการย่อยและสื่อสารผ่านอินพุต/เอาต์พุตมาตรฐาน

ไคลเอนต์ที่รองรับ:

• Claude Desktop
• Cursor IDE - โปรแกรมแก้ไขโค้ดที่ขับเคลื่อนด้วย AI
• Cline - ส่วนขยาย VS Code สำหรับความช่วยเหลือจาก AI
• Zed Editor - โปรแกรมแก้ไขโค้ดที่รวดเร็วและทันสมัย
• ไคลเอนต์ MCP อื่นๆ ที่รองรับการขนส่ง STDIO

สำหรับ Claude Desktop MCPB bundle เป็นเส้นทางที่ง่ายที่สุด สำหรับไคลเอนต์อื่นๆ ให้กำหนดค่าแพ็คเกจ npm ด้วยแฟล็ก --stdio

การกำหนดค่า - เลือกหนึ่งวิธี:

วิธีที่ 1: ใช้ npx (แนะนำ - ไม่ต้องติดตั้ง)

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

วิธีที่ 2: ใช้การติดตั้งแบบ global

ขั้นแรก ติดตั้งแบบ global:

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

จากนั้นกำหนดค่า:

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

ตำแหน่งไฟล์การกำหนดค่า:

• Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) หรือ %USERPROFILE%\.cursor\mcp.json (Windows)
• Cline: เข้าถึงได้ผ่าน UI การตั้งค่าใน VS Code
• Zed Editor: ติดตั้งเป็นส่วนขยาย MCP ผ่านตลาดส่วนขยาย

สำหรับคุณสมบัติเฉพาะของไคลเอนต์และการแก้ไขปัญหา โปรดดูเอกสารประกอบของไคลเอนต์ MCP ของคุณ ดูเพิ่มเติมที่ เชื่อมต่อกับ Claude Desktop สำหรับการกำหนดค่าที่ชี้ไปยัง dist/main-stdio.js ที่สร้างขึ้นโดยตรง

HTTP (AI บนเว็บในเครื่อง)

โหมด HTTP รันเซิร์ฟเวอร์เป็นเว็บเซิร์ฟเวอร์ในเครื่องที่ใช้โปรโตคอล MCP Streamable HTTP เป็นการขนส่งที่เครื่องมือ AI บนเว็บใช้สื่อสารเมื่อชี้ไปที่เครื่องของคุณ และยังเป็นสิ่งที่ตัวเลือก Remote เปิดเผยสู่โลกภายนอกอีกด้วย โดยตัวมันเอง โหมด HTTP จะผูกกับ localhost เท่านั้น

การผูกนอกเหนือจาก localhost? หากคุณส่ง --host 0.0.0.0 (หรือรันหลังรีเวิร์สพร็อกซี/โดเมนสาธารณะ) เซิร์ฟเวอร์จะยอมรับเฉพาะส่วนหัว Host ของลูปแบ็คตามค่าเริ่มต้นเพื่อป้องกัน DNS-rebinding — ตั้งค่า ALLOWED_HOSTS เป็นชื่อโฮสต์ที่ไคลเอนต์ใช้ ดู การกำหนดค่าโหมด HTTP

การตั้งค่า - เลือกหนึ่งวิธี:

วิธีที่ 1: ใช้ npx (แนะนำ - ไม่ต้องติดตั้ง)

# 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

วิธีที่ 2: ใช้การติดตั้งแบบ global

# 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

วิธีที่ 3: ติดตั้งจากซอร์ส (สำหรับการพัฒนา)

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

ในการทำให้เซิร์ฟเวอร์ HTTP ภายในเครื่องสามารถเข้าถึงได้โดย AI ที่โฮสต์บนคลาวด์ ให้ใช้หนึ่งในตัวเลือก Remote ด้านล่าง

Remote

AI ที่โฮสต์/ระยะไกล (เช่น ChatGPT หรือ Claude.ai ที่รันบนคลาวด์) ไม่สามารถเข้าถึง localhost ได้โดยตรง ตัวเลือกเหล่านี้จะเปิดเผย Anki ภายในเครื่อง ของคุณสู่อินเทอร์เน็ต เพื่อให้ผู้ช่วยระยะไกลสามารถสื่อสารกับมันได้

Tunnel (✅ แนะนำ)

เส้นทางระยะไกลที่แนะนำ — รับรองความถูกต้องและปลอดภัย โหมด Tunnel แตกต่างจากพอร์ตสาธารณะทั่วไป โดยกำหนดให้คุณต้องเข้าสู่ระบบ (OAuth 2.0 device flow) ดังนั้นปลายทางจะไม่เปิดให้ใครก็ตามที่เดา URL ได้

โหมด Tunnel ช่วยให้ผู้ช่วย AI บนเว็บสามารถเข้าถึง Anki ภายในเครื่อง ของคุณได้ โดยไม่ต้องรันทันเนลด้วยตัวเอง เซิร์ฟเวอร์จะเชื่อมต่อออกไปยังบริการ AnkiMCP tunnel ที่มีการจัดการ (wss://tunnel.ankimcp.ai) ผ่าน WebSocket และได้รับ URL สาธารณะ การรับรองความถูกต้องมีมาในตัว — ไม่ต้องใช้บัญชี ngrok หรือกระบวนการทันเนลแยกต่างหาก และคุณเข้าสู่ระบบเพียงครั้งเดียว

เข้าสู่ระบบ (OAuth device flow):

โหมด Tunnel ใช้ OAuth 2.0 Device Authorization Grant การเข้าสู่ระบบจะเปิดเบราว์เซอร์ของคุณไปยังหน้าอนุมัติโดยอัตโนมัติ โดยมีโค้ดฝังอยู่ใน URL แล้ว — ไม่ต้องพิมพ์อะไร แค่อนุมัติ (หากเบราว์เซอร์ไม่สามารถเปิดได้ เทอร์มินัลจะพิมพ์ URL การยืนยันและโค้ดให้ป้อนด้วยตนเองเป็นทางเลือกสำรอง) เมื่อสำเร็จ ข้อมูลประจำตัวจะถูกบันทึกไปที่ ~/.ankimcp/credentials.json (สิทธิ์ไฟล์ 0600)

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

# Clear saved credentials
ankimcp --logout

เริ่ม 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

หากไม่มีข้อมูลประจำตัว --tunnel จะเริ่มขั้นตอนการเข้าสู่ระบบโดยอัตโนมัติก่อน จากนั้นจึงดำเนินการต่อที่ tunnel การเข้าสู่ระบบอัตโนมัตินี้ต้องใช้เทอร์มินัลแบบโต้ตอบ — เมื่อ stdout ไม่ใช่ TTY (systemd, headless Docker, CI) เซิร์ฟเวอร์จะล้มเหลวอย่างรวดเร็วและขอให้คุณรัน ankimcp --login ก่อน เมื่อเชื่อมต่อแล้ว URL tunnel สาธารณะจะถูกพิมพ์; กด Ctrl+C เพื่อตัดการเชื่อมต่อ แชร์ URL นั้นกับผู้ช่วย AI ของคุณ

ตัวแปรสภาพแวดล้อมโหมด Tunnel:

ตัวแปร	คำอธิบาย	ค่าเริ่มต้น
TUNNEL_SERVER_URL	Tunnel server WebSocket URL (ค่าสถานะ --tunnel/--login จะแทนที่ค่านี้)	wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_ID	OAuth client ID สำหรับ device flow ขั้นสูง — จำเป็นเฉพาะเมื่อชี้ไปยังบริการ tunnel/auth ที่โฮสต์เอง	(ในตัว)

ปลายทางการรับรองความถูกต้องของ device-flow (/auth/device, /auth/token) ได้มาจาก TUNNEL_SERVER_URL ดังนั้นการชี้ --tunnel (หรือ TUNNEL_SERVER_URL) ไปยังโฮสต์อื่น จะย้ายการรับรองความถูกต้องไปยังโฮสต์นั้นด้วย

วิธีการทำงาน: โหมด Tunnel รันเซิร์ฟเวอร์ MCP ในกระบวนการเบื้องหลังการขนส่งในหน่วยความจำ (McpModule เริ่มต้นโดยไม่มีการขนส่งในตัว) TunnelMcpService เชื่อมต่อการขนส่งในหน่วยความจำนั้นเข้ากับเซิร์ฟเวอร์ MCP และ TunnelClient เชื่อมต่อไปยังบริการ tunnel ระยะไกลผ่าน WebSocket — ถ่ายทอดคำขอ MCP เข้าและการตอบสนองออก AnkiConnect ยังคงเข้าถึงได้เฉพาะบนเครื่องภายในของคุณเท่านั้น

ngrok (ทางเลือกที่ไม่มีการรับรองความถูกต้อง)

หากคุณต้องการเปิดเผย โหมด HTTP ภายในเครื่อง แบบสาธารณะโดยไม่มีบัญชีบน managed tunnel สถานะ --ngrok ในตัวจะเปิดใช้กระบวนการย่อย ngrok (src/services/ngrok.service.ts) และพิมพ์ URL สาธารณะในแบนเนอร์เริ่มต้น:

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

เส้นทางนี้ ไม่มีการรับรองความถูกต้อง — ใครก็ตามที่มี URL สามารถเข้าถึง Anki ของคุณได้ ดังนั้นจึงปลอดภัยน้อยกว่า Tunnel แนะนำให้ใช้ Tunnel เว้นแต่คุณจะมีเหตุผลเฉพาะในการจัดการปลายทาง ngrok ของคุณเอง (ต้องติดตั้ง ngrok แบบ global และ authtoken)

สถานะ --ngrok เปิดใช้ ngrok ด้วย --host-header=rewrite ดังนั้น ngrok จะเขียน Host ต้นทางใหม่เป็น localhost ก่อนส่งต่อ ซึ่งจะทำให้คำขออยู่ภายในรายการอนุญาตโฮสต์แบบ loopback (ดู การป้องกัน DNS-rebinding) โดยที่คุณไม่ต้องเพิ่มโดเมน *.ngrok สาธารณะไปยัง ALLOWED_HOSTS หากคุณรัน ngrok ด้วยตนเองแทน ให้ใช้สถานะเดียวกัน — ngrok http --host-header=rewrite 3000 — มิฉะนั้น ngrok จะส่งต่อชื่อโฮสต์สาธารณะของ ngrok เป็น Host และเซิร์ฟเวอร์จะปฏิเสธด้วย 403

ตัวเลือก CLI (ทุกโหมด)

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -p, --port <port>              Port to listen on (HTTP mode, default: 3000)
  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks all write operations)
  --help                         Show help message

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

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

โหมดอ่านอย่างเดียว (ทุกโหมด)

สถานะ --read-only ป้องกันการแก้ไขใดๆ ในคอลเลกชัน Anki ของคุณ เมื่อเปิดใช้งาน:

• การดำเนินการอ่านทั้งหมดทำงานได้ตามปกติ (เรียกดูสำรับ ดูการ์ด ค้นหาโน้ต)
• อนุญาตให้ดำเนินการทบทวน (sync, answerCards, suspend/unsuspend)
• บล็อกการแก้ไขเนื้อหา (addNote, deleteNotes, createDeck, updateNoteFields ฯลฯ)
• มีประโยชน์สำหรับการสำรวจข้อมูล Anki อย่างปลอดภัยโดยไม่มีความเสี่ยงต่อการเปลี่ยนแปลงโดยไม่ตั้งใจ

# 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

คุณยังสามารถเปิดใช้งานโหมดอ่านอย่างเดียวผ่านตัวแปรสภาพแวดล้อม:

READ_ONLY=true ankimcp

หรือในการกำหนดค่า MCP client:

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

เชื่อมต่อกับ Claude Desktop (โหมด Local)

คุณสามารถกำหนดค่าเซิร์ฟเวอร์ใน Claude Desktop ได้โดย:

• ไปที่: Settings → Developer → Edit Config
• หรือแก้ไขไฟล์กำหนดค่าด้วยตนเอง

การกำหนดค่า

เพิ่มสิ่งต่อไปนี้ลงในการกำหนดค่า Claude Desktop ของคุณ:

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

แทนที่ /path/to/anki-mcp-server ด้วยพาธโปรเจกต์จริงของคุณ

ตำแหน่งไฟล์กำหนดค่า

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

สำหรับรายละเอียดเพิ่มเติม โปรดดู เอกสาร MCP อย่างเป็นทางการ

ตัวแปรสภาพแวดล้อม (ไม่บังคับ)

ตัวแปร	คำอธิบาย	ค่าเริ่มต้น
ANKI_CONNECT_URL	AnkiConnect URL	http://localhost:8765
ANKI_CONNECT_API_VERSION	เวอร์ชัน API	6
ANKI_CONNECT_API_KEY	คีย์ API หากกำหนดค่าใน AnkiConnect	-
ANKI_CONNECT_TIMEOUT	หมดเวลาคำขอในหน่วย ms	5000
READ_ONLY	เปิดใช้งานโหมดอ่านอย่างเดียว (true หรือ 1)	false
ALLOWED_HOSTS	โหมด HTTP: ค่าส่วนหัว Host เพิ่มเติมที่ยอมรับนอกเหนือจาก loopback (ชื่อโฮสต์ที่คั่นด้วยเครื่องหมายจุลภาค) จำเป็นเมื่อผูกกับที่อยู่ LAN/สาธารณะ หรือรันหลัง reverse proxy ดู การกำหนดค่าโหมด HTTP	loopback เท่านั้น
ALLOWED_ORIGINS	โหมด HTTP: รายการอนุญาตของรูปแบบ Origin/Referer ของเบราว์เซอร์ที่คั่นด้วยเครื่องหมายจุลภาค (รองรับไวลด์การ์ด เช่น https://*.ngrok.io)	http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URL	Tunnel server WebSocket URL (โหมด tunnel เท่านั้น)	wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPES	ประเภท MIME เพิ่มเติมที่อนุญาตสำหรับการนำเข้าพาธไฟล์ (คั่นด้วยเครื่องหมายจุลภาค เช่น application/pdf)	-
MEDIA_IMPORT_DIR	จำกัดการนำเข้าพาธไฟล์ไว้ที่ไดเรกทอรีนี้	-
MEDIA_ALLOWED_HOSTS	อนุญาตโฮสต์เครือข่ายส่วนตัวเฉพาะสำหรับการนำเข้า URL (คั่นด้วยเครื่องหมายจุลภาค เช่น 192.168.1.50,my-nas)	-

ตัวอย่างการใช้งาน

การค้นหาและอัปเดตโน้ต

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

ตัวอย่างไวยากรณ์การสืบค้น Anki

เครื่องมือ findNotes รองรับไวยากรณ์การสืบค้นอันทรงพลังของ Anki:

• "deck:DeckName" - โน้ตทั้งหมดในสำรับที่ระบุ
• "tag:important" - โน้ตที่มีแท็ก "important"
• "is:due" - การ์ดที่ถึงกำหนดทบทวน
• "is:new" - การ์ดใหม่ที่ยังไม่ได้ศึกษา
• "added:7" - โน้ตที่เพิ่มใน 7 วันที่ผ่านมา
• "front:hello" - โน้ตที่มี "hello" ในฟิลด์ด้านหน้า
• "flag:1" - โน้ตที่มีธงสีแดง
• "prop:due<=2" - การ์ดที่ถึงกำหนดภายใน 2 วัน
• "deck:Spanish tag:verb" - โน้ตสำรับภาษาสเปนที่มีแท็ก verb (AND)
• "deck:Spanish OR deck:French" - โน้ตจากสำรับใดสำรับหนึ่ง

หมายเหตุสำคัญ

การจัดการ CSS และ HTML

• เครื่องมือ notesInfo ส่งคืนข้อมูลสไตล์ CSS เพื่อการรับรู้การแสดงผลที่เหมาะสม
• เครื่องมือ updateNoteFields รองรับเนื้อหา HTML ในฟิลด์และรักษาสไตล์ CSS
• โมเดลโน้ตแต่ละรายการมีสไตล์ CSS ของตัวเอง - ใช้ modelStyling เพื่อรับ CSS เฉพาะของโมเดล

คำเตือนการอัปเดต

⚠️ สำคัญ: เมื่อใช้ updateNoteFields ห้ามดูโน้ตในเบราว์เซอร์ของ Anki ขณะอัปเดต มิฉะนั้นฟิลด์จะไม่อัปเดตอย่างถูกต้อง ปิดเบราว์เซอร์หรือสลับไปยังโน้ตอื่นก่อนอัปเดต ดู ปัญหาที่ทราบ สำหรับรายละเอียดเพิ่มเติม

ความปลอดภัยในการลบ

เครื่องมือ deleteNotes ต้องการการยืนยันอย่างชัดเจน (confirmDeletion: true) เพื่อป้องกันการลบโดยไม่ตั้งใจ การลบโน้ตจะลบการ์ดที่เกี่ยวข้องทั้งหมดอย่างถาวร

ความปลอดภัย

การตรวจสอบพาธไฟล์สื่อและ URL

เครื่องมือสื่อ (storeMediaFile, retrieveMediaFile, deleteMediaFile) และฟิลด์เสียง/รูปภาพ updateNoteFields รวมถึงการตรวจสอบความปลอดภัยเพื่อป้องกันการใช้งานในทางที่ผิดผ่านการแทรกคำสั่ง:

• การนำเข้าพาธไฟล์ ถูกจำกัดเฉพาะประเภทไฟล์สื่อเท่านั้น (รูปภาพ เสียง วิดีโอ) ไฟล์ที่ไม่ใช่สื่อ (เช่น คีย์ SSH ข้อมูลประจำตัว การกำหนดค่าเชลล์) จะถูกปฏิเสธตามประเภท MIME กำหนดค่า MEDIA_ALLOWED_TYPES เพื่ออนุญาตประเภทไฟล์เพิ่มเติม หรือ MEDIA_IMPORT_DIR เพื่อจำกัดการนำเข้าไว้ที่ไดเรกทอรีเฉพาะ
• การนำเข้า URL ถูกตรวจสอบกับการโจมตี SSRF คำขอไปยังเครือข่ายส่วนตัว (10.x, 172.16.x, 192.168.x), loopback (127.x), link-local (169.254.x) และรูปแบบที่ไม่ใช่ HTTP(S) จะถูกบล็อก กำหนดค่า MEDIA_ALLOWED_HOSTS เพื่ออนุญาตโฮสต์เครือข่ายส่วนตัวเฉพาะ
• ชื่อไฟล์ ถูกทำให้ปลอดภัยเพื่อป้องกันการ traversal พาธ (เช่น ลำดับ ../../ จะถูกตัดออก)

การป้องกันเหล่านี้ใช้กับ storeMediaFile, retrieveMediaFile, deleteMediaFile และฟิลด์เสียง/รูปภาพ updateNoteFields

ช่องโหว่ Path traversal รายงานโดย Hideaki Takahashi

การป้องกัน DNS-Rebinding (การขนส่ง HTTP)

เมื่อรันในโหมด HTTP เซิร์ฟเวอร์จะตรวจสอบส่วนหัว Host ในทุกคำขอ โดยค่าเริ่มต้นจะยอมรับเฉพาะโฮสต์ loopback (localhost, 127.0.0.1, ::1) โดยไม่คำนึงถึงพอร์ต Host เป็นส่วนหัวที่เบราว์เซอร์ห้ามส่ง ดังนั้นหน้าเว็บที่เป็นอันตรายจึงไม่สามารถปลอมแปลงได้ — นี่เป็นการปิดเส้นทาง DNS-rebinding ที่หน้า rebound เข้าถึงเซิร์ฟเวอร์ภายในด้วย Host ปลอมและไม่มี Origin และเข้าถึงเครื่องมือ MCP Host ที่ไม่อนุญาตจะถูกปฏิเสธด้วย 403

หากคุณผูกกับ 0.0.0.0 รันหลัง reverse proxy หรือเปิดเผยโดเมน tunnel สาธารณะ ให้ตั้งค่า ALLOWED_HOSTS (ชื่อโฮสต์ที่คั่นด้วยเครื่องหมายจุลภาค) เพื่ออนุญาตโฮสต์เหล่านั้น เมื่อทำ tunnel ด้วย ngrok เซิร์ฟเวอร์จะใช้ --host-header=rewrite ดังนั้นต้นทางจะยังเห็น Host แบบ loopback ดู การกำหนดค่าโหมด HTTP สำหรับรายการตัวเลือกทั้งหมด

ช่องโหว่ DNS-rebinding รายงานโดย avishaigo-commits และ yotampe-pluto

นโยบายความเป็นส่วนตัว

เซิร์ฟเวอร์ MCP นี้รันภายในเครื่องของคุณและไม่เก็บรวบรวมข้อมูลทางไกล การวิเคราะห์ หรือข้อมูลการใช้งาน

นโยบายฉบับเต็ม: https://ankimcp.ai/privacy/

• การเก็บรวบรวมข้อมูล: เซิร์ฟเวอร์ไม่เก็บรวบรวมสิ่งใด มันทำหน้าที่เป็นพร็อกซีคำขอระหว่างผู้ช่วย AI ของคุณและปลั๊กอิน AnkiConnect ภายในเครื่องของคุณ
• การใช้งาน / การจัดเก็บ: ไม่มีการจัดเก็บฝั่งเซิร์ฟเวอร์ ข้อมูลแฟลชการ์ดทั้งหมดยังคงอยู่ในการติดตั้ง Anki ของคุณบนอุปกรณ์ของคุณเอง
• การแบ่งปันกับบุคคลที่สาม: ไม่มี เซิร์ฟเวอร์สื่อสารกับ URL AnkiConnect ที่คุณกำหนดค่าเท่านั้น (ค่าเริ่มต้น: localhost) หากคุณเปิดใช้งานการซิงค์ AnkiWeb ในตัวของ Anki การดำเนินการนั้นจะเกิดขึ้นระหว่างการติดตั้ง Anki ของคุณกับ AnkiWeb โดยตรง — อยู่นอกขอบเขตของเซิร์ฟเวอร์นี้
• การเก็บรักษา: ไม่สามารถใช้ได้ — ไม่มีข้อมูลถูกเก็บรักษาฝั่งเซิร์ฟเวอร์
• ติดต่อ: support@ankimcp.ai

ปัญหาที่ทราบ

สำหรับรายการปัญหาที่ทราบและข้อจำกัดที่ครอบคลุม โปรดเยี่ยมชมเอกสารของเรา:

เอกสารปัญหาที่ทราบ

ข้อจำกัดที่สำคัญ

การอัปเดตโน้ตล้มเหลวเมื่อดูในเบราว์เซอร์

⚠️ สำคัญ: เมื่ออัปเดตโน้ตโดยใช้ updateNoteFields การอัปเดตจะล้มเหลวอย่างเงียบๆ หากกำลังดูโน้ตนั้นในหน้าต่างเบราว์เซอร์ของ Anki นี่เป็นข้อจำกัดของ AnkiConnect ต้นทาง

วิธีแก้ไข: ปิดเบราว์เซอร์หรือนำทางไปยังโน้ตอื่นก่อนอัปเดตเสมอ

สำหรับรายละเอียดเพิ่มเติมและปัญหาอื่นๆ ที่ทราบ โปรดดู เอกสารฉบับเต็ม

การแก้ไขปัญหา

ข้อผิดพลาด ERR_REQUIRE_ESM

หากคุณเห็นข้อผิดพลาดเช่น:

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

นี่หมายความว่าเวอร์ชัน Node.js ของคุณไม่รองรับ เซิร์ฟเวอร์ต้องการ Node.js 22.12.0+

หมายเหตุ: รันไทม์ขั้นต่ำที่รองรับคือ Node.js 22.12.0 Node.js 20 (Iron) สิ้นสุดอายุการใช้งานเมื่อ 2026-04-30 และไม่ได้รับการสนับสนุนอีกต่อไป

ตรวจสอบเวอร์ชันของคุณ:

node --version

วิธีแก้ไข: อัปเดต Node.js เป็นเวอร์ชัน 22.12.0 ขึ้นไป คุณสามารถดาวน์โหลดได้จาก nodejs.org หรือใช้ตัวจัดการเวอร์ชันเช่น nvm

การพัฒนา

โหมดการขนส่ง

เซิร์ฟเวอร์นี้รองรับโหมดการขนส่ง MCP สามโหมดผ่าน จุดเข้าใช้งานที่แยกจากกัน:

โหมด STDIO (ค่าเริ่มต้น)

• สำหรับไคลเอนต์ MCP ในเครื่องเช่น Claude Desktop
• ใช้อินพุต/เอาต์พุตมาตรฐานสำหรับการสื่อสาร
• จุดเข้าใช้งาน: dist/main-stdio.js
• รัน: npm run start:prod:stdio หรือ node dist/main-stdio.js
• บันเดิล MCPB: ใช้โหมด STDIO

โหมด HTTP (Streamable HTTP)

• สำหรับไคลเอนต์ MCP ระยะไกลและการผสานรวมบนเว็บ
• ใช้โปรโตคอล MCP Streamable HTTP
• จุดเข้าใช้งาน: dist/main-http.js
• รัน: npm run start:prod:http หรือ node dist/main-http.js
• พอร์ตเริ่มต้น: 3000 (กำหนดค่าได้ผ่านตัวแปรสภาพแวดล้อม PORT)
• โฮสต์เริ่มต้น: 127.0.0.1 (กำหนดค่าได้ผ่านตัวแปรสภาพแวดล้อม HOST)
• จุดสิ้นสุด MCP: http://127.0.0.1:3000/ (พาธราก)

โหมด Tunnel (Managed WebSocket Tunnel)

• สำหรับผู้ช่วย AI บนเว็บผ่านบริการ AnkiMCP tunnel ที่มีการจัดการ พร้อมการตรวจสอบสิทธิ์ในตัว
• เซิร์ฟเวอร์ MCP ทำงานในกระบวนการเบื้องหลังการขนส่งในหน่วยความจำ; TunnelMcpService เชื่อมต่อกับเซิร์ฟเวอร์ MCP และ TunnelClient เชื่อมต่อไปยังบริการ tunnel ผ่าน WebSocket
• จุดเข้าใช้งาน: dist/main-tunnel.js
• รัน: node dist/main-tunnel.js --tunnel (หรือ ankimcp --tunnel)
• การตรวจสอบสิทธิ์: ankimcp --login / ankimcp --logout; ข้อมูลประจำตัวถูกเก็บไว้ที่ ~/.ankimcp/credentials.json (0600)
• การพัฒนา: npm run start:dev:tunnel (โหมด watch, รัน --tunnel --debug)

การสร้าง

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

main-stdio.js, main-http.js และ main-tunnel.js ทั้งหมดถูกสร้างลงในไดเรกทอรี dist/ เดียวกัน เลือกที่จะรันตามความต้องการของคุณ

การกำหนดค่าโหมด HTTP

ตัวแปรสภาพแวดล้อม:

• PORT - พอร์ตเซิร์ฟเวอร์ HTTP (ค่าเริ่มต้น: 3000)
• HOST - ที่อยู่การผูก (ค่าเริ่มต้น: 127.0.0.1 สำหรับ localhost เท่านั้น)
• ALLOWED_HOSTS - ค่าเฮดเดอร์ Host พิเศษที่ยอมรับนอกเหนือจากชุด loopback ในตัว (localhost, 127.0.0.1, ::1) คั่นด้วยเครื่องหมายจุลภาค เฉพาะชื่อโฮสต์และไม่สนใจพอร์ต ค่าเริ่มต้น: loopback เท่านั้น
• ALLOWED_ORIGINS - รายการอนุญาตของรูปแบบ Origin/Referer ของเบราว์เซอร์ คั่นด้วยเครื่องหมายจุลภาค; รองรับไวลด์การ์ด (เช่น https://*.ngrok.io) ค่าเริ่มต้น: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
• LOG_LEVEL - ระดับการบันทึก (ค่าเริ่มต้น: info)

ความปลอดภัย:

• การตรวจสอบความถูกต้องของเฮดเดอร์ Host (การป้องกัน DNS-rebinding) — ทุกคำขอ HTTP ต้องมีเฮดเดอร์ Host ที่ตรงกับรายการอนุญาต ตามค่าเริ่มต้นจะยอมรับเฉพาะโฮสต์ loopback (localhost, 127.0.0.1, ::1) โดยไม่คำนึงถึงพอร์ต Host เป็นเฮดเดอร์ที่เบราว์เซอร์ห้ามใช้ ดังนั้นหน้าเว็บที่เป็นอันตรายจึงไม่สามารถปลอมแปลงได้ — นี่เป็นการปิดเส้นทาง DNS-rebinding ที่หน้าเว็บที่ถูกเปลี่ยนเส้นทางเข้าถึงเซิร์ฟเวอร์ด้วย Host ที่ปลอมแปลงและไม่มี Origin Host ที่ไม่อนุญาตจะถูกปฏิเสธด้วย 403
• การตรวจสอบความถูกต้องของเฮดเดอร์ Origin — คำขอของเบราว์เซอร์ที่มี Origin/Referer ที่มีอยู่แต่ไม่อนุญาตจะถูกปฏิเสธ คำขอที่ไม่มี Origin (curl, Postman, ไคลเอนต์ MCP-over-HTTP) ได้รับอนุญาต; การตรวจสอบ Host เป็นการป้องกัน rebinding
• ผูกกับ localhost (127.0.0.1) ตามค่าเริ่มต้น
• ไม่มีการตรวจสอบสิทธิ์ในเวอร์ชันปัจจุบัน (วางแผนรองรับ OAuth)

การเปิดเผยโหมด HTTP นอกเหนือ localhost — หากคุณผูกกับที่อยู่ LAN/สาธารณะ หรือวางเซิร์ฟเวอร์ไว้เบื้องหลัง reverse proxy หรือโดเมนสาธารณะ คุณต้องตั้งค่า ALLOWED_HOSTS เป็นชื่อโฮสต์ที่ไคลเอนต์จะใช้ มิฉะนั้นทุกคำขอที่ไม่ใช่ loopback จะถูกปฏิเสธด้วย 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

เมื่อคุณผูกกับ 0.0.0.0/:: โดยไม่มี ALLOWED_HOSTS เซิร์ฟเวอร์จะบันทึกคำเตือนเมื่อเริ่มต้นว่าจะยอมรับเฉพาะเฮดเดอร์ Host ของ loopback เท่านั้น

Docker / reverse proxy / โดเมนสาธารณะ: กฎเดียวกันนี้ใช้ได้ ใน Docker คำขอมักจะมาถึงพร้อมชื่อโฮสต์ที่เผยแพร่ของคอนเทนเนอร์หรือ Host ของพร็อกซี ดังนั้นให้ตั้งค่า ALLOWED_HOSTS ตามนั้น reverse proxy (nginx, Caddy, Traefik) ควรส่งต่อ Host เดิมและมีชื่อโฮสต์นั้นอยู่ใน ALLOWED_HOSTS หรือเขียน Host ต้นทางใหม่เป็น localhost การผสานรวม --ngrok ในตัวจัดการสิ่งนี้โดยอัตโนมัติ (ดูด้านล่าง)

ตัวอย่าง: โหมดการรัน

# 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

การสร้างบันเดิล MCPB

เพื่อสร้างบันเดิล MCPB ที่แจกจ่ายได้:

npm run mcpb:bundle

คำสั่งนี้จะ:

1. ซิงค์เวอร์ชันจาก package.json ไปยัง manifest.json
2. ลบไฟล์ .mcpb เก่า
3. สร้างโปรเจกต์ TypeScript
4. แพ็คเกจ dist/ และ node_modules/ ลงในไฟล์ .mcpb
5. รัน mcpb clean เพื่อลบ devDependencies (ปรับขนาดบันเดิลจาก ~47MB เป็น ~10MB)

ไฟล์เอาต์พุตจะถูกตั้งชื่อว่า anki-mcp-server-X.X.X.mcpb และสามารถแจกจ่ายสำหรับการติดตั้งแบบคลิกเดียว

สิ่งที่รวมอยู่ในบันเดิล

บันเดิล MCPB ประกอบด้วย:

• JavaScript ที่คอมไพล์แล้ว (ไดเรกทอรี dist/ - รวมจุดเข้าใช้งานทั้งสาม)
• เฉพาะ dependencies สำหรับการใช้งานจริง (node_modules/ - devDependencies ถูกลบโดย mcpb clean)
• ข้อมูลเมตาของแพ็คเกจ (package.json)
• การกำหนดค่า Manifest (manifest.json - กำหนดค่าให้ใช้ main-stdio.js)
• ไอคอน (icon.png)

ไฟล์ต้นฉบับ การทดสอบ และการกำหนดค่าการพัฒนาจะถูกยกเว้นโดยอัตโนมัติผ่าน .mcpbignore

การบันทึกใน Claude Desktop

เมื่อรันเป็นส่วนขยาย MCPB ใน Claude Desktop บันทึกจะถูกเขียนไปที่:

ตำแหน่งบันทึก: ~/Library/Logs/Claude/ (macOS)

บันทึกถูกแบ่งออกเป็นหลายไฟล์:

• main.log - บันทึกแอปพลิเคชัน Claude Desktop ทั่วไป
• mcp-server-Anki MCP Server.log - ข้อความโปรโตคอล MCP สำหรับส่วนขยายนี้
• mcp.log - บันทึก MCP รวมจากทุกเซิร์ฟเวอร์

หมายเหตุ: เอาต์พุตของ pino logger (ข้อความ INFO, ERROR, WARN จากโค้ดเซิร์ฟเวอร์) ไปที่ stderr และปรากฏในไฟล์บันทึกเฉพาะ MCP Claude Desktop กำหนดว่าไฟล์บันทึกใดได้รับข้อความใด แต่โดยทั่วไป:

• การเริ่มต้นแอปพลิเคชันและการสื่อสารโปรโตคอล MCP → บันทึกเฉพาะ MCP
• การบันทึกภายในเซิร์ฟเวอร์ (pino) → ทั้งบันทึกเฉพาะ MCP และบางครั้ง main.log

เพื่อดูบันทึกแบบเรียลไทม์:

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

การดีบักเซิร์ฟเวอร์ MCP

คุณสามารถดีบักเซิร์ฟเวอร์ MCP ได้โดยใช้ MCP Inspector และแนบดีบักเกอร์จาก IDE ของคุณ (WebStorm, VS Code ฯลฯ)

หมายเหตุสำหรับโหมด HTTP: เมื่อทดสอบโหมด HTTP (Streamable HTTP) ด้วย MCP Inspector ให้ใช้ "Connection Type: Via Proxy" เพื่อหลีกเลี่ยงข้อผิดพลาด CORS

ขั้นตอนที่ 1: กำหนดค่า Debug Server ใน MCP Inspector

mcp-inspector-config.json มีการกำหนดค่า debug server อยู่แล้ว:

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

ขั้นตอนที่ 2: เริ่ม Debug Server

รัน MCP Inspector พร้อม debug server:

npm run inspector:debug

สิ่งนี้จะเริ่มเซิร์ฟเวอร์โดยเปิดใช้งานการดีบัก Node.js บนพอร์ต 9229 และหยุดการทำงานชั่วคราวที่บรรทัดแรก

ขั้นตอนที่ 3: แนบดีบักเกอร์จาก IDE ของคุณ

WebStorm

1. ไปที่ Run → Edit Configurations
2. เพิ่มการกำหนดค่า Attach to Node.js/Chrome ใหม่
3. ตั้งค่าพอร์ตเป็น 9229
4. คลิก Debug เพื่อแนบ

VS Code

1. เปิดแผง Debug (Ctrl+Shift+D / Cmd+Shift+D)
2. เลือกการกำหนดค่า Debug MCP Server (Attach)
3. กด F5 เพื่อแนบ

ขั้นตอนที่ 4: ตั้งค่าเบรกพอยต์และดีบัก

เมื่อแนบแล้ว คุณสามารถ:

• ตั้งค่าเบรกพอยต์ในไฟล์ต้นฉบับ TypeScript ของคุณ
• ก้าวผ่านการทำงานของโค้ด
• ตรวจสอบตัวแปรและ call stack
• ใช้คอนโซลดีบักสำหรับการประเมินนิพจน์

ดีบักเกอร์จะทำงานกับ source maps ทำให้คุณสามารถดีบักโค้ด TypeScript ต้นฉบับแทน JavaScript ที่คอมไพล์แล้ว

การดีบักกับ Claude Desktop

คุณยังสามารถดีบักเซิร์ฟเวอร์ MCP ในขณะที่มันทำงานภายใน Claude Desktop ได้โดยเปิดใช้งานดีบักเกอร์ Node.js และแนบ IDE ของคุณ

ขั้นตอนที่ 1: กำหนดค่า Claude Desktop สำหรับการดีบัก

อัปเดตการกำหนดค่า Claude Desktop ของคุณเพื่อเปิดใช้งานการดีบัก:

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

การเปลี่ยนแปลงสำคัญ: เพิ่ม --inspect=9229 ก่อนพาธไปยัง dist/main-stdio.js

ตัวเลือกการดีบัก:

• --inspect=9229 - เริ่มดีบักเกอร์ทันที ไม่บล็อก (แนะนำ)
• --inspect-brk=9229 - หยุดการทำงานชั่วคราวจนกว่าดีบักเกอร์จะแนบ (สำหรับการดีบักปัญหาเริ่มต้น)

ขั้นตอนที่ 2: รีสตาร์ท Claude Desktop

หลังจากบันทึกการกำหนดค่าแล้ว ให้รีสตาร์ท Claude Desktop เซิร์ฟเวอร์ MCP จะทำงานโดยเปิดใช้งานการดีบักบนพอร์ต 9229

ขั้นตอนที่ 3: แนบดีบักเกอร์จาก IDE ของคุณ

WebStorm

1. ไปที่ Run → Edit Configurations
2. คลิกปุ่ม + และเลือก Attach to Node.js/Chrome
3. กำหนดค่า:
   • Name: Attach to Anki MCP (Claude Desktop)
   • Host: localhost
   • Port: 9229
   • Attach to: Node.js < 8 หรือ Chrome or Node.js > 6.3 (ขึ้นอยู่กับเวอร์ชันของ WebStorm)
4. คลิก OK
5. คลิก Debug (Shift+F9) เพื่อแนบ

VS Code

1. เพิ่มไปยัง .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"]
    }
  ]
}

2. เปิดแผง Debug (Ctrl+Shift+D / Cmd+Shift+D)
3. เลือก Attach to Anki MCP (Claude Desktop)
4. กด F5 เพื่อแนบ

ขั้นตอนที่ 4: ดีบักแบบเรียลไทม์

เมื่อแนบแล้ว คุณสามารถ:

• ตั้งค่าเบรกพอยต์ในไฟล์ต้นฉบับ TypeScript ของคุณ (เช่น src/mcp/primitives/essential/tools/create-model.tool.ts)
• ใช้ Claude Desktop ตามปกติ - เบรกพอยต์จะทำงานเมื่อมีการเรียกใช้เครื่องมือ
• ก้าวผ่านการทำงานของโค้ด
• ตรวจสอบตัวแปรและ call stack
• ใช้คอนโซลดีบัก

ตัวอย่าง: ตั้งค่าเบรกพอยต์ใน create-model.tool.ts ที่บรรทัด 119 จากนั้นขอให้ Claude สร้างโมเดลใหม่ ดีบักเกอร์จะหยุดที่เบรกพอยต์ของคุณ!

หมายเหตุ: ดีบักเกอร์ยังคงแนบอยู่ตราบเท่าที่ Claude Desktop กำลังทำงาน คุณสามารถถอด/แนบใหม่ได้ตลอดเวลาโดยไม่ต้องรีสตาร์ท Claude Desktop

คำสั่งสร้าง

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

การทดสอบแพ็คเกจ NPM (ในเครื่อง)

ทดสอบแพ็คเกจ npm ในเครื่องก่อนเผยแพร่:

# 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

วิธีการทำงาน:

• npm pack สร้างไฟล์ .tgz ที่เหมือนกับที่ npm publish จะสร้าง
• การติดตั้งจาก .tgz จำลองสิ่งที่ผู้ใช้ได้รับจาก npm install -g ankimcp
• สิ่งนี้ช่วยให้คุณทดสอบประสบการณ์ผู้ใช้เต็มรูปแบบก่อนเผยแพร่ไปยัง npm

คำสั่งทดสอบ

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)

ความครอบคลุมของการทดสอบ

โปรเจกต์รักษาเกณฑ์ความครอบคลุมขั้นต่ำ 70% สำหรับ:

• Branches
• Functions
• Lines
• Statements

รายงานความครอบคลุมถูกสร้างขึ้นในไดเรกทอรี coverage/

การกำหนดเวอร์ชัน

โปรเจกต์นี้ปฏิบัติตาม Semantic Versioning ด้วยแนวทางการพัฒนาก่อนเวอร์ชัน 1.0:

• 0.x.x - เวอร์ชันเบต้า/การพัฒนา (เฟสปัจจุบัน)

  • 0.1.x - การแก้ไขข้อบกพร่องและแพตช์
  • 0.2.0+ - ฟีเจอร์ใหม่หรือการปรับปรุงเล็กน้อย
  • การเปลี่ยนแปลงที่เข้ากันไม่ได้ เป็นที่ยอมรับได้ในเวอร์ชัน 0.x

• 1.0.0 - รุ่นเสถียรรุ่นแรก

  • จะเผยแพร่เมื่อ API เสถียรและผ่านการทดสอบ
  • การเปลี่ยนแปลงที่เข้ากันไม่ได้จะต้องเพิ่มเวอร์ชันหลัก (2.0.0 เป็นต้นไป)

สถานะปัจจุบัน: 0.22.0 - การพัฒนาเบต้าที่ใช้งานอยู่ ฟีเจอร์ล่าสุดรวมถึงการวิเคราะห์รีวิวทั่วทั้งคอลเลกชัน (review_stats ตอนนี้รวมข้อมูลจากทุกสำรับเมื่อละเว้น deck), การจัดการฟิลด์โมเดล (addModelField, removeModelField, renameModelField, repositionModelField), การสร้างโน้ตแบบกลุ่ม (addNotes), การทำ ngrok tunnel ในตัว (แฟล็ก --ngrok), การจัดการไฟล์มีเดีย, การจัดการโมเดล/เทมเพลต และสถิติสำรับที่ครอบคลุม API อาจเปลี่ยนแปลงตามความคิดเห็นและการทดสอบ

วิวัฒนาการของสเปก MCPB

โปรเจกต์นี้กำหนดเป้าหมายไปที่สเปก MCPB bundle ของ Anthropic ซึ่งยังคงพัฒนาอยู่ เราติดตามสเปกที่ https://github.com/modelcontextprotocol/mcpb และอาจแนะนำการเปลี่ยนแปลงที่เข้ากันไม่ได้เพื่อให้เป็นไปตามข้อกำหนด การเปลี่ยนแปลงที่เข้ากันไม่ได้ได้รับอนุญาตภายใต้รูปแบบการกำหนดเวอร์ชัน 0.x.x

โปรเจกต์ที่คล้ายกัน

หากคุณกำลังสำรวจการผสานรวม Anki MCP นี่คือโปรเจกต์อื่นๆ ในพื้นที่นี้:

scorzeth/anki-mcp-server

• สถานะ: ดูเหมือนจะถูกยกเลิก (ไม่มีการอัปเดตล่าสุด)
• การใช้งานการผสานรวม Anki MCP ในช่วงแรก

nailuoGG/anki-mcp-server

• แนวทาง: การใช้งานแบบน้ำหนักเบา ไฟล์เดียว
• สถาปัตยกรรม: โครงสร้างโค้ดแบบโพรซีเดอร์ พร้อมเครื่องมือทั้งหมดในไฟล์เดียว
• เหมาะสำหรับ: กรณีการใช้งานที่เรียบง่าย การพึ่งพาแพ็กเกจน้อยที่สุด

เหตุผลที่โปรเจกต์นี้แตกต่าง:

• สถาปัตยกรรมระดับองค์กร: สร้างบน NestJS พร้อมการฉีดดีเพนเดนซี
• การออกแบบแบบโมดูลาร์: แต่ละเครื่องมือเป็นคลาสแยกต่างหาก พร้อมการแบ่งแยกหน้าที่อย่างชัดเจน
• ความสามารถในการบำรุงรักษา: ง่ายต่อการขยายด้วยฟีเจอร์ใหม่ โดยไม่ต้องแก้ไขโค้ดที่มีอยู่
• การทดสอบ: ชุดทดสอบที่ครอบคลุม พร้อมข้อกำหนดความครอบคลุม 70%
• ความปลอดภัยของประเภทข้อมูล: TypeScript แบบเข้มงวด พร้อมการตรวจสอบด้วย Zod
• การจัดการข้อผิดพลาด: การจัดการข้อผิดพลาดที่แข็งแกร่ง พร้อมข้อเสนอแนะที่เป็นประโยชน์ต่อผู้ใช้
• พร้อมสำหรับการใช้งานจริง: การบันทึกข้อมูล การรายงานความคืบหน้า และการสนับสนุน MCPB bundle อย่างเหมาะสม
• ความสามารถในการปรับขนาด: สามารถเติบโตจากเครื่องมือพื้นฐานไปสู่เวิร์กโฟลว์ที่ซับซ้อนได้อย่างง่ายดาย

กรณีการใช้งาน: หากคุณต้องการรากฐานที่มั่นคงสำหรับการสร้างการผสานรวม Anki ขั้นสูง หรือวางแผนที่จะขยายฟังก์ชันการทำงานอย่างมีนัยสำคัญ แนวทางสถาปัตยกรรมของโปรเจกต์นี้ทำให้ง่ายต่อการบำรุงรักษาและปรับขนาดเมื่อเวลาผ่านไป

ลิงก์ที่มีประโยชน์

• เอกสารประกอบ Model Context Protocol
• เอกสารประกอบ AnkiConnect API
• ดาวน์โหลด Claude Desktop
• การสร้างส่วนขยายเดสก์ท็อป (บล็อก Anthropic)
• ที่เก็บ MCP Servers
• เอกสารประกอบ NestJS
• เว็บไซต์ทางการของ Anki

ใบอนุญาตและการระบุแหล่งที่มา

โปรเจกต์นี้ได้รับอนุญาตภายใต้ MIT License — ดู LICENSE สำหรับข้อความฉบับเต็ม

ลิขสิทธิ์ © 2026 Anatoly Tarnavsky

การระบุแหล่งที่มาของบุคคลที่สาม

• Anki® เป็นเครื่องหมายการค้าจดทะเบียนของ Ankitects Pty Ltd โปรเจกต์นี้เป็นเครื่องมือของบุคคลที่สามอย่างไม่เป็นทางการ และไม่มีส่วนเกี่ยวข้อง รับรอง หรือสนับสนุนโดย Ankitects Pty Ltd โลโก้ Anki ใช้ภายใต้ใบอนุญาตทางเลือกสำหรับการอ้างอิง Anki พร้อมลิงก์ไปยัง https://apps.ankiweb.net สำหรับแอปพลิเคชัน Anki อย่างเป็นทางการ โปรดเยี่ยมชม https://apps.ankiweb.net

• Model Context Protocol (MCP) เป็นมาตรฐานเปิดโดย Anthropic โลโก้ MCP มาจาก ที่เก็บเอกสารประกอบ MCP อย่างเป็นทางการ และใช้ภายใต้ MIT License สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ MCP โปรดเยี่ยมชม https://modelcontextprotocol.io

• นี่คือโปรเจกต์อิสระที่เชื่อมต่อเทคโนโลยี Anki และ MCP เครื่องหมายการค้า เครื่องหมายบริการ ชื่อทางการค้า ชื่อผลิตภัณฑ์ และโลโก้ทั้งหมดเป็นทรัพย์สินของเจ้าของที่เกี่ยวข้อง