Anki MCP

Anki MCP Sunucusu

[!IMPORTANT] Çoğu kurulum için AnkiMCP eklentisini tercih edin.

Eklenti (GitHub), MCP sunucusunu doğrudan Anki'nin içinde çalıştırır. Kurulacak Node.js yok, yapılandırılacak AnkiConnect yok, çalışır durumda tutulacak ayrı bir süreç yok: 124672614 koduyla kurun, Anki'yi yeniden başlatın ve sunucu Anki her açıldığında hazır olur. Yerel HTTP erişimini ve yerleşik bir tünel aracılığıyla uzaktan erişimi kapsar.

Bu depo, özellikle şunlara ihtiyaç duyduğunuzda doğru seçimdir:

• STDIO taşıma — Claude Desktop, Claude Code, Cursor veya sunucuyu alt süreç olarak başlatan herhangi bir istemci
• MCPB paketi — Claude Desktop için tek tıklamayla .mcpb kurulumu

HTTP, tünel veya web tabanlı istemciler (claude.ai, ChatGPT) için eklenti daha basit ve daha iyi desteklenen yoldur.

Bu depo kullanımdan kaldırılmıyor. Aynı ankimcp.ai projesinin parçası olarak eklentiyle birlikte bakımı yapılıyor ve yayınlanıyor.

Yapay zeka asistanlarının Anki ile, yani aralıklı tekrar flashcard uygulamasıyla etkileşime girmesini sağlayan bir Model Context Protocol (MCP) sunucusu.

Anki deneyiminizi doğal dil etkileşimiyle dönüştürün - özel bir öğretmene sahip olmak gibi. Yapay zeka asistanı yalnızca soruları ve cevapları sunmaz; kavramları açıklayabilir, öğrenme sürecini daha ilgi çekici ve insani hale getirebilir, bağlam sağlayabilir ve öğrenme stilinize uyum sağlayabilir. Anında notlar oluşturabilir ve düzenleyebilir, çalışma oturumlarınızı dinamik sohbetlere dönüştürebilir. Yakında daha fazla özellik gelecek!

Örnekler ve Eğiticiler

Bu MCP sunucusunu Claude Desktop ile kullanmaya yönelik kapsamlı rehberler, gerçek dünya örnekleri ve adım adım eğiticiler için şu adresi ziyaret edin:

ankimcp.ai - Pratik örnekler ve kullanım senaryolarıyla eksiksiz dokümantasyon

Ek dokümantasyon için docs/ bölümüne bakın; gözden geçiren kurulum rehberi ve örnek Anki destesini içerir.

Örnek Kullanım Senaryoları

Bu sunucunun etkinleştirdiği araç akışlarını gösteren üç temsili komut:

1. "İspanyolca destemi gözden geçirmeme yardım et." — Asistan AnkiWeb ile senkronize olmayı teklif eder (sync), vadesi gelen kartları getirir (get_due_cards deste filtresiyle), her kartı sunar (present_card) ve puanınızı kaydeder (rate_card). Size göre uyarlanmış açıklamalarla doğal çalışma sohbeti.

2. "RTL stillendirmeli 10 Arapça kelime kartı oluştur." — Asistan not türlerini listeler (modelNames), gerekirse özel bir RTL modeli oluşturur (sağdan sola CSS için createModel + updateModelStyling) ve ardından kartları toplu olarak oluşturur (addNotes).

3. "İndirilenler klasörümdeki bu görseli seçili notun ön yüzüne aktar." — Asistan yerel dosyayı yükler (dosya yoluyla storeMediaFile), tarayıcıdan şu anda seçili notu okur (guiSelectedNotes + notesInfo) ve ön alanı bir <img> etiketiyle günceller (updateNoteFields).

Mevcut Araçlar

Sunucu 53 MCP aracı sunar — günlük Anki işlemleri için 42 temel araç ve not düzenleme/oluşturma iş akışları için Anki masaüstü arayüzünü yönlendiren 11 GUI aracı.

Temel Araçlar

Gözden Geçirme ve Çalışma

• sync - En son verileri çekmek ve değişiklikleri göndermek için AnkiWeb ile senkronize edin
• get_due_cards - Gözden geçirme için vadesi gelen kartları alın, isteğe bağlı olarak desteye göre filtrelenir (include_answer: true olmadığı sürece cevaplar atlanır, varsayılan false)
• get_cards - Duruma (vadesi gelmiş, yeni, öğreniliyor, askıya alınmış, gömülü) ve desteye göre esnek filtrelemeyle kartları alın (include_answer: true olmadığı sürece cevaplar atlanır, varsayılan false)
• present_card - Soru/ön yüzüyle birlikte gözden geçirme için bir kart gösterin
• rate_card - Kart performansını derecelendirin (Tekrar, Zor, İyi, Kolay) ve bir sonraki gözden geçirmeyi planlayın
• forgetCards - Bir gözden geçirme kaydetmeden kartları yeni durumuna sıfırlayın, zamanlamalarını atın
• setDueDate - Bir gözden geçirme kaydetmeden kartları N gün içinde vadesi gelecek şekilde yeniden planlayın ("0", "3-7", "1!")
• areSuspended - Hiçbir şeyi değiştirmeden bir veya daha fazla kartın askıya alınma durumunu kontrol edin
• suspend - Askıdan çıkarılana kadar gözden geçirme sırasında atlanmaları için kartları askıya alın
• unsuspend - Normal gözden geçirmeye dönmeleri için kartların askısını kaldırın

Not: forgetCards ve setDueDate, zamanlamayı bir gözden geçirme kaydetmeden değiştirir; bu da onları rate_card'dan ayıran şeydir. Bir kartın zamanlaması yanlış olduğunda cevaptan ziyade bunlara başvurun: bir kartı daha derine gömmek için Again olarak derecelendirmek gerçek bir tekrar hatası kaydeder ve kolaylık faktörünü düşürür, hem gelecekteki zamanlamayı hem de istatistiklerinizi kalıcı olarak çarpıtır. forgetCards aralığı siler ve karta yeniden başlar; setDueDate kartın geçmişini korur ve yalnızca bir sonraki gözden geçirmeyi taşır.

Not: Kart front/back içeriği, Anki'nin gösterdiği gibi kendi şablonundan kart başına işlenir; böylece ters ve boşluk doldurma kartları doğru yönü görüntüler. Kart şablonlarınız tarafından eklenen statik metin de çıktıda görünür.

Deste Yönetimi

• listDecks - Tüm desteleri, isteğe bağlı olarak deste başına çalışma kuyruğu istatistikleriyle birlikte listeleyin
• deckStats - Tek bir deste için kapsamlı istatistikler alın (çalışma kuyruğu, gerçek kart durumu sayıları, kolaylık/aralık dağılımları)
• createDeck - Yeni bir boş deste oluşturun (Parent::Child destekler, en fazla 2 seviye)
• changeDeck - Kartları farklı bir desteye taşıyın (yoksa oluşturulur)

Not: Deste istatistikleri iki türde gelir. counts bloğu (ve listDecks'nin bildirdiği her şey) Anki'nin deste tarayıcısını yansıtır: her destenin günlük yeni/tekrar limitleriyle sınırlandırılmış, askıya alınmış ve gömülü kartlar hariç, bugün vadesi gelen kartlar — bu nedenle review "olgun kartlar" değildir ve other paketi yalnızca aritmetik kalandır (çoğunlukla bugün vadesi gelmeyen tekrar kartları artı günlük limitin üzerindeki yeni kartlar). Gerçek durum toplamları için deckStats / collection_stats üzerindeki states bloğunu kullanın; bu blok, vade tarihlerini ve günlük limitleri yok sayarak Anki aramalarıyla new, learning, review, suspended ve buried sayar.

Not Yönetimi

• addNote - Belirtilen alanlar ve etiketlerle tek bir not oluşturun
• addNotes - Bir deste ve modeli paylaşan en fazla 100 notu toplu olarak oluşturun (kısmi başarı desteklenir)
• findNotes - Anki sorgu sözdizimini kullanarak notları arayın (deck:, tag:, is:due, vb.)
• notesInfo - Notlar hakkında ayrıntılı bilgi alın (alanlar, etiketler, not türü, kart kimlikleri; CSS modelStyling'dan gelir)
• updateNoteFields - Mevcut not alanlarını güncelleyin (CSS duyarlı, HTML içeriği destekler)
• deleteNotes - Notları ve ilişkili tüm kartları silin (yıkıcı, onay gerektirir)

Etiket Yönetimi

• getTags - Koleksiyondaki tüm etiketleri alın (çoğaltmayı önlemek için önce kullanın)
• addTags - Belirtilen notlara boşlukla ayrılmış etiketler ekleyin
• removeTags - Belirtilen notlardan boşlukla ayrılmış etiketleri kaldırın
• replaceTags - Belirtilen notlarda bir etiketi yeniden adlandırın
• clearUnusedTags - Hiçbir not tarafından kullanılmayan sahipsiz etiketleri kaldırın (yıkıcı)

Medya Yönetimi

• getMediaFilesNames - collection.media içindeki medya dosyalarını listeleyin, isteğe bağlı olarak desene göre filtrelenir
• retrieveMediaFile - Bir medya dosyasını base64 içerik olarak indirin
• storeMediaFile - Base64 verilerinden, mutlak bir dosya yolundan veya bir URL'den medya yükleyin
• deleteMediaFile - collection.media içinden bir medya dosyasını kaldırın (yıkıcı)

💡 Görseller için En İyi Uygulama:

• ✅ Dosya yollarını kullanın (örn. /Users/you/image.png) - Hızlı ve verimli
• ✅ URL'leri kullanın (örn. https://example.com/image.jpg) - Doğrudan indirme
• ❌ Base64'ten kaçının - Son derece yavaş ve token açısından verimsiz

Claude'a görselin nerede olduğunu söylemeniz yeterlidir; en verimli yöntemi kullanarak yüklemeyi otomatik olarak halleder.

Model/Şablon Yönetimi

• modelNames - Mevcut tüm not türlerini/modelleri listeleyin
• modelFieldNames - Belirli bir not türü için alan adlarını alın
• modelStyling - Bir not türü için CSS stillendirme bilgilerini alın
• modelTemplates - Bir not türü için kart şablonlarını (Ön ve Arka HTML) alın
• createModel - Özel alanlar, kart şablonları ve CSS ile yeni bir not türü oluşturun (örn. RTL modelleri)
• updateModelStyling - Mevcut bir not türü için CSS stillendirmesini güncelleyin (tüm kartlarına uygulanır)
• updateModelTemplates - Mevcut bir not türü için kart şablonlarını (Ön ve Arka HTML) güncelleyin (tüm kartlarına uygulanır)
• addModelField - Mevcut bir not türüne yeni bir alan ekleyin (sona eklenir veya belirli bir konuma eklenir)
• removeModelField - Mevcut bir not türünden bir alanı kaldırın (içeriğini tüm notlardan siler; açık onay gerektirir)
• renameModelField - Mevcut bir not türünde bir alanı yeniden adlandırın (Anki, kart şablonlarındaki eski ad referanslarını yeniden yazar)
• repositionModelField - Mevcut bir not türü içinde bir alanın konumunu değiştirin

İstatistikler

• collection_stats - Deste başına döküm ve koleksiyon genelinde kart durumu sayılarıyla tüm destelerdeki toplu istatistikler
• review_stats - Gözden geçirme geçmişi analizi (zamansal desenler, hatırlama metrikleri, çalışma serileri)

GUI Araçları

Anki masaüstü arayüzünü yönlendiren araçlar. Not düzenleme/oluşturma ve deste yönetimi iş akışları için tasarlanmıştır, gözden geçirme oturumları için değil.

• guiBrowse - Kart Tarayıcısını açın ve kartları arayın
• guiSelectCard - Kart Tarayıcısında belirli bir kartı seçin
• guiSelectedNotes - Kart Tarayıcısında şu anda seçili notların kimliklerini alın
• guiAddCards - Önceden ayarlanmış not ayrıntılarıyla Kart Ekle iletişim kutusunu açın
• guiEditNote - Belirli bir not için not düzenleyiciyi açın
• guiDeckOverview - Belirli bir deste için Deste Genel Bakış iletişim kutusunu açın
• guiDeckBrowser - Deste Tarayıcısı iletişim kutusunu açın
• guiCurrentCard - Gözden geçirme modundaki geçerli kart hakkında bilgi alın (cevabı içerir; gözden geçirme modu dışında hata verir)
• guiShowQuestion - Geçerli kartın soru tarafını gösterin
• guiShowAnswer - Geçerli kartın cevap tarafını gösterin
• guiUndo - Anki'deki son eylemi geri alın

Ön Koşullar

• AnkiConnect eklentisi yüklü Anki
• Node.js 22.12.0+

Kurulum

Sunucuyu makinenize almanın birkaç yolu vardır. Kurulduktan sonra, onu yapay zeka asistanınıza — yerel veya uzaktan — bağlamak için Bir Yapay Zeka İstemcisini Bağlama bölümüne gidin.

npm (global veya npx)

Sunucuyu kurmanın genel amaçlı yolu, onu doğrudan başlatan herhangi bir MCP istemcisi için uygundur.

ankimcp komutunu çalıştıran istemciler için global olarak kurun:

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

Veya kurulum gerektirmeden isteğe bağlı olarak çalıştırın:

npx @ankimcp/anki-mcp-server

MCPB Paketi (Claude Desktop için Önerilir)

Bu MCP sunucusunu Claude Desktop için kurmanın en kolay yolu:

1. Sürümler sayfasından en son .mcpb paketini indirin
2. Claude Desktop'ta uzantıyı kurun:
   • Yöntem 1: Ayarlar → Uzantılar'a gidin ve .mcpb dosyasını sürükleyip bırakın
   • Yöntem 2: Ayarlar → Geliştirici → Uzantılar → Uzantı Kur'a gidin ve .mcpb dosyasını seçin
3. Gerekirse AnkiConnect URL'sini yapılandırın (varsayılan http://localhost:8765)
4. Claude Desktop'u yeniden başlatın

Bu kadar! Paket, sunucuyu yerel olarak çalıştırmak için gereken her şeyi içerir.

Anthropic MCP Dizin inceleyicileri için: önceden doldurulmuş örnek bir desteyle sıfırdan entegrasyona kadar adım adım bir kılavuz docs/reviewer-setup.md içinde yer alır.

Kaynaktan Kurulum (geliştirme için)

For development or advanced usage (running the test suite requires Node.js 24.9+ — the npm test scripts load the ESM-only NestJS 12 packages via require(esm), which Jest only supports there; the runtime requirement for using the server stays 22.12.0+):

npm install
npm run build

Bir Yapay Zeka İstemcisi Bağlama

Bir yapay zeka asistanının bu sunucuya ulaşmasının iki yolu vardır; bu, asistanın nerede çalıştığına bağlıdır:

• Yerel — sunucu, yapay zeka istemcisiyle (Claude Desktop, Cursor, Cline, Zed veya yerel bir tarayıcı oturumu) aynı makinede çalışır. Masaüstü MCP istemcileri için STDIO, yerel web tabanlı araçlar için HTTP kullanın.
• Uzak — barındırılan/uzak bir yapay zeka (ör. bulutta çalışan ChatGPT veya Claude.ai), yerel makinenizde çalışan Anki'ye ulaşmalıdır. Yönetilen Tunnel'ı (✅ önerilir — kimlik doğrulamalı) veya daha hafif, kimlik doğrulamasız bir alternatif olarak ngrok'u kullanın.

Yerel

Sunucu, yapay zeka istemcinizle aynı bilgisayarda çalışır ve localhost üzerinden AnkiConnect ile konuşur.

STDIO (birincil yerel entegrasyon)

STDIO, yerel masaüstü MCP istemcileri için standart taşıma katmanıdır — Claude Desktop, Cursor IDE, Cline, Zed Editor, opencode ve diğerleri. İstemci, sunucuyu bir alt süreç olarak başlatır ve standart giriş/çıkış üzerinden iletişim kurar.

Desteklenen İstemciler:

• Claude Desktop
• Cursor IDE - Yapay zeka destekli kod editörü
• Cline - Yapay zeka yardımı için VS Code uzantısı
• Zed Editor - Hızlı, modern kod editörü
• opencode - Terminal yapay zeka kodlama aracısı
• STDIO taşıma katmanını destekleyen diğer MCP istemcileri

Claude Desktop için MCPB paketi en kolay yoldur. Diğer istemciler için npm paketini --stdio bayrağıyla yapılandırın.

Yapılandırma - Bir yöntem seçin:

Yöntem 1: npx kullanma (önerilir - kurulum gerekmez)

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

Yöntem 2: Global kurulum kullanma

Önce global olarak kurun:

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

Ardından yapılandırın:

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

opencode kendi formatını kullanır — sunucular mcp altına gider, komut tek bir dizidir ve ortam değişkenleri environment altına gider:

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

Yapılandırma dosyası konumları:

• Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) veya %USERPROFILE%\.cursor\mcp.json (Windows)
• Cline: VS Code'da ayarlar arayüzü üzerinden erişilebilir
• Zed Editor: Uzantı pazarı üzerinden MCP uzantısı olarak kurun
• opencode: Proje kökünde opencode.json veya global olarak ~/.config/opencode/opencode.json

İstemciye özel özellikler ve sorun giderme için MCP istemcinizin belgelerine bakın. Ayrıca, doğrudan derlenmiş bir dist/main-stdio.js işaret eden bir yapılandırma için Claude Desktop'a Bağlanma bölümüne bakın.

HTTP (yerel web tabanlı yapay zeka)

HTTP modu, sunucuyu MCP Streamable HTTP protokolünü konuşan yerel bir web sunucusu olarak çalıştırır. Web tabanlı bir yapay zeka aracının makinenize işaret edildiğinde konuştuğu taşıma katmanıdır ve aynı zamanda Uzak seçeneklerinin dış dünyaya açtığı şeydir. Tek başına HTTP modu yalnızca localhost adresine bağlanır.

Localhost'un ötesine bağlanmak mı? --host 0.0.0.0 (veya ters proxy/genel alan adı arkasında çalışıyorsanız) geçirirseniz, sunucu DNS yeniden bağlama koruması için varsayılan olarak yalnızca geri döngü Host başlıklarını kabul eder — istemcilerin kullandığı ana bilgisayar ad(lar)ını ALLOWED_HOSTS olarak ayarlayın. HTTP Modu Yapılandırması bölümüne bakın.

Kurulum - Bir yöntem seçin:

Yöntem 1: npx kullanma (önerilir - kurulum gerekmez)

# 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

Yöntem 2: Global kurulum kullanma

# 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

Yöntem 3: Kaynaktan kurma (geliştirme için)

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

Yerel bir HTTP sunucusunu bulut barındırmalı bir yapay zeka tarafından erişilebilir kılmak için aşağıdaki Uzak seçeneklerinden birini kullanın.

Uzak

Barındırılan/uzak bir yapay zeka (bulutta çalışan ChatGPT veya Claude.ai gibi) localhost adresine doğrudan ulaşamaz. Bu seçenekler yerel Anki'nizi internete açarak uzak bir asistanın onunla konuşmasını sağlar.

Tunnel (✅ Önerilir)

Önerilen uzak yol — kimlik doğrulamalı ve güvenli. Ham bir genel bağlantı noktasının aksine, tünel modu oturum açmanızı gerektirir (OAuth 2.0 cihaz akışı), böylece uç nokta URL'yi tahmin eden herkese açık değildir.

Tünel modu, web tabanlı yapay zeka asistanlarının kendi tünelinizi çalıştırmadan yerel Anki'nize ulaşmasını sağlar. Sunucu, yönetilen AnkiMCP tünel hizmetine (wss://tunnel.ankimcp.ai) bir WebSocket üzerinden bağlanır ve kendisine genel bir URL atanır. Kimlik doğrulama yerleşiktir — ngrok hesabı veya ayrı bir tünel süreci gerekmez ve bir kez oturum açarsınız.

Oturum açma (OAuth cihaz akışı):

Tünel modu, OAuth 2.0 Cihaz Yetkilendirme Hibe akışını kullanır. Oturum açma, tarayıcınızı otomatik olarak kodun URL'ye gömülü olduğu bir onay sayfasına açar — yazılacak bir şey yok, sadece onaylayın. (Tarayıcı açılamazsa, terminal yedek olarak manuel girilecek bir doğrulama URL'si ve kod yazdırır.) Başarılı olursa, kimlik bilgileri ~/.ankimcp/credentials.json konumuna kaydedilir (dosya izinleri 0600).

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

# Clear saved credentials
ankimcp --logout

Tüneli başlatın:

# 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

Kimlik bilgileri yoksa, --tunnel otomatik olarak önce oturum açma akışını başlatır, ardından tünele devam eder. Bu otomatik oturum açma etkileşimli bir terminal gerektirir — stdout bir TTY olmadığında (systemd, başsız Docker, CI), sunucu hızlı bir şekilde başarısız olur ve önce ankimcp --login çalıştırmanızı ister. Bağlandıktan sonra genel tünel URL'si yazdırılır; bağlantıyı kesmek için Ctrl+C'ye basın. Bu URL'yi yapay zeka asistanınızla paylaşın.

Tünel modu ortam değişkenleri:

Değişken	Açıklama	Varsayılan
TUNNEL_SERVER_URL	Tünel sunucusu WebSocket URL'si (--tunnel/--login bayrak değeri bunu geçersiz kılar)	wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_ID	Cihaz akışı için OAuth istemci kimliği. Gelişmiş — yalnızca kendi kendine barındırılan bir tünel/auth hizmetini işaret ederken gerekir.	(yerleşik)

Cihaz akışı kimlik doğrulama uç noktaları (/auth/device, /auth/token) TUNNEL_SERVER_URL adresinden türetilir; bu nedenle --tunnel (veya TUNNEL_SERVER_URL) farklı bir ana bilgisayarı işaret etmek, kimlik doğrulamayı da o ana bilgisayara taşır.

Nasıl çalışır: Tünel modu, MCP sunucusunu bellek içi bir taşıma katmanının (TunnelTransport) arkasında süreç içinde çalıştırır. Bu taşıma katmanı MCP sunucusuna sahiptir ve her aktarılan istek gövdesini bir yanıta dönüştürür; TunnelClient ise bunu uzak tünel hizmetine bir WebSocket üzerinden köprüleyerek MCP isteklerini içeri ve yanıtları dışarı aktarır. AnkiConnect'e yine yalnızca yerel makinenizde erişilir.

Protokol sürümleri: Tünel, MCP sunucusunu süreç içinde bağladığından, tünel modu yalnızca MCP protokolünün 2025 sürümüne hizmet eder; STDIO ve HTTP modları ise hem 2025 hem de daha yeni 2026-07-28 sürümüne hizmet eder. Her araç her iki durumda da aynı şekilde davranır — ancak yalnızca 2026-07-28 konuşan bir istemci, tünel üzerinden bir protokol sürümü hatasıyla geri çevrilir; bu istemci için STDIO veya HTTP modunu çalıştırın.

ngrok (kimlik doğrulamasız alternatif)

Yönetilen tünelde hesap olmadan yerel HTTP modunu herkese açık hale getirmeyi tercih ederseniz, yerleşik --ngrok bayrağı bir ngrok alt süreci başlatır (src/services/ngrok.service.ts) ve genel URL'yi başlangıç başlığında yazdırır:

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

Bu yol kimlik doğrulamasızdır — URL'ye sahip herkes Anki'nize ulaşabilir, bu nedenle Tunnel kadar güvenli değildir. Kendi ngrok uç noktanızı yönetmek için belirli bir nedeniniz yoksa Tunnel'ı tercih edin. (Global bir ngrok kurulumu ve authtoken gerektirir.)

--ngrok bayrağı ngrok'u --host-header=rewrite ile başlatır; böylece ngrok, iletmeden önce yukarı akış Host adresini localhost olarak yeniden yazar. Bu, istekleri geri döngü Host beyaz listesinde tutar (bkz. DNS yeniden bağlama koruması) ve genel *.ngrok alan adını ALLOWED_HOSTS eklemeniz gerekmez. Bunun yerine ngrok'u manuel çalıştırırsanız, aynı bayrağı kullanın — ngrok http --host-header=rewrite 3000 — aksi takdirde ngrok genel ngrok ana bilgisayar adını Host olarak iletir ve sunucu bunu 403 ile reddeder.

CLI Seçenekleri (tüm modlar)

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

Salt Okunur Mod (tüm modlar)

--read-only bayrağı (veya READ_ONLY=true), not içeriği, desteler, etiketler, medya ve not türleri ile kartların manuel yeniden planlanmasındaki değişiklikleri engeller. Etkinleştirildiğinde:

• Tüm okuma işlemleri normal çalışır (destelere göz atma, kartları görüntüleme, notları arama)
• Bu değişikliklere hâlâ izin verilir: gözden geçirme sırasında kartı derecelendirme (rate_card), kartları askıya alma/askıdan çıkarma (suspend, unsuspend), AnkiWeb ile senkronizasyon (sync) ve Anki pencerelerinde gezinmek için GUI araçları (guiBrowse, guiDeckOverview, …)
• İçerik değişiklikleri engellenir (addNote, deleteNotes, createDeck, updateNoteFields, vb.); zaten var olan bir deste için createDeck yine de başarılı olur, çünkü hiçbir şey yazılmaz
• Manuel yeniden planlama engellenir: forgetCards (yeniye sıfırlama) ve setDueDate
• guiUndo engellenir, çünkü bir geri alma koleksiyondaki bir değişikliği geri alabilir
• guiAddCards ve guiEditNote engellenir, çünkü açtıkları iletişim kutusunda eklenen veya kaydedilen bir not koleksiyona yazılır
• Anki verilerini içeriğinde yanlışlıkla değişiklik yapmadan keşfetmek için kullanışlıdır

# 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

Salt okunur modu ortam değişkeniyle de etkinleştirebilirsiniz:

READ_ONLY=true ankimcp

Veya MCP istemci yapılandırmasında:

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

Claude Desktop'a Bağlanma (Yerel Mod)

Sunucuyu Claude Desktop'ta şu şekilde yapılandırabilirsiniz:

• Şuraya giderek: Ayarlar → Geliştirici → Yapılandırmayı Düzenle
• Veya yapılandırma dosyasını manuel olarak düzenleyerek

Yapılandırma

Claude Desktop yapılandırmanıza aşağıdakileri ekleyin:

{
  "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 yerine gerçek proje yolunuzu yazın.

Yapılandırma Dosyası Konumları

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

Daha fazla ayrıntı için resmi MCP belgelerine bakın.

Ortam Değişkenleri (İsteğe Bağlı)

Değişken	Açıklama	Varsayılan
ANKI_CONNECT_URL	AnkiConnect URL'si	http://localhost:8765
ANKI_CONNECT_API_VERSION	API sürümü	6
ANKI_CONNECT_API_KEY	AnkiConnect'te yapılandırılmışsa API anahtarı	-
ANKI_CONNECT_TIMEOUT	ms cinsinden istek zaman aşımı	5000
READ_ONLY	Salt okunur modu etkinleştir (true veya 1)	false
PORT	HTTP modu: dinlenecek bağlantı noktası (--port bayrağı önceliklidir)	3000
HOST	HTTP modu: bağlanılacak adres (--host bayrağı önceliklidir)	127.0.0.1
ALLOWED_HOSTS	HTTP modu: geri döngü dışında kabul edilecek ek Host başlık değerleri (virgülle ayrılmış ana bilgisayar adları). LAN/genel adrese bağlanırken veya ters proxy arkasında çalışırken gereklidir. HTTP Modu Yapılandırması bölümüne bakın.	yalnızca geri döngü
ALLOWED_ORIGINS	HTTP modu: virgülle ayrılmış tarayıcı Origin/Referer desenleri beyaz listesi (joker karakterler desteklenir, ör. https://*.ngrok.io).	http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*
TUNNEL_SERVER_URL	Tünel sunucusu WebSocket URL'si (yalnızca tünel modu)	wss://tunnel.ankimcp.ai
MEDIA_ALLOWED_TYPES	Dosya yolu içe aktarmaları için izin verilecek ek MIME türleri (virgülle ayrılmış, ör. application/pdf)	-
MEDIA_IMPORT_DIR	Dosya yolu içe aktarmalarını bu dizine kısıtla	-
MEDIA_ALLOWED_HOSTS	URL içe aktarmaları için belirli özel ağ ana bilgisayarlarına izin ver (virgülle ayrılmış, ör. 192.168.1.50,my-nas)	-

Kullanım Örnekleri

Notları Arama ve Güncelleme

# 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 Sorgu Sözdizimi Örnekleri

findNotes aracı, Anki'nin güçlü sorgu sözdizimini destekler:

• "deck:DeckName" - Belirli bir destedeki tüm notlar
• "tag:important" - "önemli" etiketine sahip notlar
• "is:due" - Tekrar zamanı gelmiş kartlar
• "is:new" - Henüz çalışılmamış yeni kartlar
• "added:7" - Son 7 günde eklenen notlar
• "front:hello" - Ön alanında "merhaba" yazan notlar
• "flag:1" - Kırmızı bayraklı notlar
• "prop:due<=2" - 2 gün içinde tekrar zamanı gelen kartlar
• "deck:Spanish tag:verb" - Fiil etiketli İspanyolca deste notları (VE)
• "deck:Spanish OR deck:French" - Her iki desteden notlar

Önemli Notlar

CSS ve HTML İşleme

• notesInfo aracı her notun not tipi adını döndürür; CSS'in kendisi modelStyling'dan gelir
• updateNoteFields aracı alanlarda HTML içeriğini destekler ve CSS stillerini korur
• Her not modelinin kendi CSS stili vardır - modele özgü CSS almak için modelStyling kullanın

Güncelleme Uyarısı

⚠️ ÖNEMLİ: updateNoteFields kullanırken, güncelleme sırasında notu Anki'nin tarayıcısında GÖRÜNTÜLEMEYİN, aksi takdirde alanlar düzgün güncellenmez. Güncellemeden önce tarayıcıyı kapatın veya farklı bir nota geçin. Ayrıntılar için Bilinen Sorunlar bölümüne bakın.

Silme Güvenliği

deleteNotes aracı, yanlışlıkla silmeleri önlemek için açık onay (confirmDeletion: true) gerektirir. Bir notu silmek, ilişkili TÜM kartları kalıcı olarak kaldırır.

Güvenlik

Medya Dosya Yolu ve URL Doğrulama

Medya araçları (storeMediaFile, retrieveMediaFile, deleteMediaFile) ve updateNoteFields ses/resim alanları, komut enjeksiyonu yoluyla kötüye kullanımı önlemek için güvenlik doğrulaması içerir:

• Dosya yolu içe aktarımları yalnızca medya dosya türleriyle (görüntüler, ses, video) sınırlıdır. Medya olmayan dosyalar (ör. SSH anahtarları, kimlik bilgileri, kabuk yapılandırmaları) MIME türüne göre reddedilir. Ek dosya türlerine izin vermek için MEDIA_ALLOWED_TYPES yapılandırın veya içe aktarımları belirli bir dizine kısıtlamak için MEDIA_IMPORT_DIR kullanın.
• URL içe aktarımları SSRF saldırılarına karşı doğrulanır. Özel ağlara (10.x, 172.16.x, 192.168.x), geri döngü (127.x), bağlantı-yerel (169.254.x) ve HTTP(S) olmayan şemalara yapılan istekler engellenir. Belirli özel ağ ana bilgisayarlarına izin vermek için MEDIA_ALLOWED_HOSTS yapılandırın.
• Dosya adları, yol geçişini önlemek için temizlenir (ör. ../../ dizileri kaldırılır).

Bu korumalar storeMediaFile, retrieveMediaFile, deleteMediaFile ve updateNoteFields ses/resim alanları için geçerlidir.

Yol geçişi güvenlik açığı Hideaki Takahashi tarafından bildirildi.

DNS-Yeniden Bağlama Koruması (HTTP taşıma)

HTTP modunda çalışırken sunucu, her istekte Host başlığını doğrular. Varsayılan olarak yalnızca geri döngü ana bilgisayarları (localhost, 127.0.0.1, ::1) bağlantı noktasından bağımsız olarak kabul edilir. Host tarayıcı tarafından yasaklanmış bir başlıktır, bu nedenle kötü niyetli bir web sayfası bunu taklit edemez - bu, yeniden bağlanan bir sayfanın sahte Host ile ve Origin olmadan yerel sunucuya ulaştığı ve MCP araçlarına eriştiği DNS-yeniden bağlama yolunu kapatır. İzin verilmeyen bir Host, 403 ile reddedilir.

0.0.0.0'ye bağlanırsanız, bir ters proxy arkasında çalışırsanız veya genel bir tünel alan adı açığa çıkarırsanız, bu ana bilgisayarlara izin vermek için ALLOWED_HOSTS (virgülle ayrılmış ana bilgisayar adları) ayarlayın. ngrok ile tünel açarken sunucu --host-header=rewrite kullanır, bu nedenle yukarı akış hala bir geri döngü Host görür. Seçeneklerin tam listesi için HTTP Modu Yapılandırması bölümüne bakın.

DNS-yeniden bağlama güvenlik açığı avishaigo-commits ve yotampe-pluto tarafından bildirildi.

Gizlilik Politikası

Bu MCP sunucusu makinenizde yerel olarak çalışır ve hiçbir telemetri, analiz veya kullanım verisi toplamaz.

Tam politika: https://ankimcp.ai/privacy/

• Veri toplama: Sunucu hiçbir şey toplamaz. Yapay zeka asistanınız ile yerel AnkiConnect eklentiniz arasındaki istekleri iletir.
• Kullanım / depolama: Sunucu tarafında depolama yoktur. Tüm flashcard verileri, kendi cihazınızdaki Anki kurulumunuzda kalır.
• Üçüncü taraf paylaşımı: Yok. Sunucu yalnızca yapılandırdığınız AnkiConnect URL'siyle (varsayılan: localhost) konuşur. Anki'nin yerleşik AnkiWeb senkronizasyonunu etkinleştirirseniz, bu doğrudan Anki kurulumunuz ile AnkiWeb arasında gerçekleşir - bu sunucunun kapsamı dışındadır.
• Saklama: Geçerli değil - sunucu tarafında hiçbir veri saklanmaz.
• İletişim: support@ankimcp.ai

Bilinen Sorunlar

Bilinen sorunların ve sınırlamaların kapsamlı bir listesi için lütfen dokümantasyonumuzu ziyaret edin:

Bilinen Sorunlar Dokümantasyonu

Kritik Sınırlamalar

Tarayıcıda Görüntülendiğinde Not Güncellemeleri Başarısız Olur

⚠️ ÖNEMLİ: updateNoteFields kullanarak notları güncellerken, not şu anda Anki'nin tarayıcı penceresinde görüntüleniyorsa güncelleme sessizce başarısız olur. Bu, üst akış AnkiConnect sınırlamasıdır.

Geçici çözüm: Güncellemeden önce her zaman tarayıcıyı kapatın veya farklı bir nota gidin.

Daha fazla ayrıntı ve diğer bilinen sorunlar için tam dokümantasyona bakın.

Sorun Giderme

ERR_REQUIRE_ESM Hatası

Aşağıdaki gibi bir hata görürseniz:

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

Bu, Node.js sürümünüzün desteklenmediği anlamına gelir. Sunucu Node.js 22.12.0+ gerektirir.

Not: Desteklenen minimum çalışma zamanı Node.js 22.12.0'dır. Node.js 20 (Iron) 2026-04-30 tarihinde kullanım ömrünün sonuna ulaşmıştır ve artık desteklenmemektedir.

Sürümünüzü kontrol edin:

node --version

Çözüm: Node.js'i 22.12.0+ sürümüne güncelleyin. nodejs.org adresinden indirebilir veya nvm gibi bir sürüm yöneticisi kullanabilirsiniz.

Geliştirme

Taşıma Modları

Bu sunucu, ayrı giriş noktaları aracılığıyla üç MCP taşıma modunu destekler:

STDIO Modu (Varsayılan)

• Claude Desktop gibi yerel MCP istemcileri için
• İletişim için standart giriş/çıkış kullanır
• Giriş noktası: dist/main-stdio.js
• Çalıştırma: npm run start:prod:stdio veya node dist/main-stdio.js
• MCPB paketi: STDIO modunu kullanır

HTTP Modu (Akışkan HTTP)

• Uzak MCP istemcileri ve web tabanlı entegrasyonlar için
• MCP Akışkan HTTP protokolünü kullanır
• Giriş noktası: dist/main-http.js
• Çalıştırma: npm run start:prod:http veya node dist/main-http.js
• Varsayılan bağlantı noktası: 3000 (PORT env değişkeniyle yapılandırılabilir)
• Varsayılan ana bilgisayar: 127.0.0.1 (HOST env değişkeniyle yapılandırılabilir)
• MCP uç noktası: http://127.0.0.1:3000/ (kök yol)

Tünel Modu (Yönetilen WebSocket Tüneli)

• Yerleşik kimlik doğrulamalı, yönetilen AnkiMCP tünel hizmeti aracılığıyla web tabanlı yapay zeka asistanları için
• MCP sunucusu, bellek içi bir taşımanın arkasında süreç içinde çalışır; TunnelTransport MCP sunucusuna sahiptir ve TunnelClient onu bir WebSocket üzerinden tünel hizmetine köprüler
• Protokol: yalnızca 2025 MCP revizyonunu sunar (STDIO ve HTTP ayrıca 2026-07-28 sürümünü de sunar)
• Giriş noktası: dist/main-tunnel.js
• Çalıştırma: node dist/main-tunnel.js --tunnel (veya ankimcp --tunnel)
• Kimlik doğrulama: ankimcp --login / ankimcp --logout; kimlik bilgileri ~/.ankimcp/credentials.json adresinde saklanır (0600)
• Geliştirme: npm run start:dev:tunnel (izleme modu, --tunnel --debug çalıştırır)

Derleme

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

main-stdio.js, main-http.js ve main-tunnel.js aynı dist/ dizinine derlenir. İhtiyaçlarınıza göre hangisini çalıştıracağınızı seçin.

HTTP Modu Yapılandırması

Ortam Değişkenleri:

• PORT - HTTP sunucu bağlantı noktası (varsayılan: 3000)
• HOST - Bağlama adresi (varsayılan: yalnızca localhost için 127.0.0.1)
• ALLOWED_HOSTS - Yerleşik geri döngü kümesinin (localhost, 127.0.0.1, ::1) ötesinde kabul edilecek virgülle ayrılmış ek Host başlık değerleri. Yalnızca ana bilgisayar adı ve bağlantı noktasından bağımsız. Varsayılan: yalnızca geri döngü.
• ALLOWED_ORIGINS - Tarayıcı Origin/Referer desenlerinin virgülle ayrılmış beyaz listesi; joker karakterler desteklenir (ör. https://*.ngrok.io). Varsayılan: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
• LOG_LEVEL - Günlük kaydı düzeyi (varsayılan: bilgi)

Güvenlik:

• Ana bilgisayar başlığı doğrulaması (DNS-yeniden bağlama koruması) — her HTTP isteği, beyaz listeyle eşleşen bir Host başlığı taşımalıdır. Varsayılan olarak yalnızca geri döngü ana bilgisayarları (localhost, 127.0.0.1, ::1) bağlantı noktasından bağımsız olarak kabul edilir. Host tarayıcı tarafından yasaklanmış bir başlıktır, bu nedenle kötü niyetli bir web sayfası bunu taklit edemez - bu, yeniden bağlanan bir sayfanın sahte Host ile ve Origin olmadan sunucuya ulaştığı DNS-yeniden bağlama yolunu kapatır. İzin verilmeyen bir Host, 403 ile reddedilir.
• Origin başlığı doğrulaması — mevcut ancak izin verilmeyen bir Origin/Referer içeren tarayıcı istekleri reddedilir. Hiçbir Origin içermeyen isteklere (curl, Postman, MCP-over-HTTP istemcileri) izin verilir; Ana bilgisayar doğrulaması, yeniden bağlamaya karşı savunmadır.
• Varsayılan olarak localhost'a (127.0.0.1) bağlanır.
• Geçerli sürümde kimlik doğrulama yoktur (OAuth desteği planlanmaktadır).

HTTP modunu localhost dışına açma — bir LAN/genel adrese bağlanırsanız veya sunucuyu bir ters proxy veya genel alan adının arkasına koyarsanız, istemcilerin kullanacağı ana bilgisayar ad(lar)ını ALLOWED_HOSTS olarak ayarlamanız gerekir, aksi takdirde geri döngü olmayan her istek 403 ile reddedilir:

# 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/:: değerine ALLOWED_HOSTS olmadan bağlandığınızda, sunucu yalnızca geri döngü Host başlıklarının kabul edileceğine dair bir başlangıç uyarısı günlüğe kaydeder.

Docker / ters proxy / genel alan adı: aynı kural geçerlidir. Docker'da istekler genellikle kapsayıcının yayınlanan ana bilgisayar adı veya proxy'nin Host değeriyle gelir, bu nedenle ALLOWED_HOSTS değerini buna göre ayarlayın. Bir ters proxy (nginx, Caddy, Traefik) orijinal Host değerini iletmeli ve bu ana bilgisayar adını ALLOWED_HOSTS içinde listelemeli veya yukarı akış Host değerini localhost olarak yeniden yazmalıdır. Yerleşik --ngrok entegrasyonu bunu otomatik olarak halleder (aşağıya bakın).

Örnek: Çalıştırma Modları

# 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 Paketi Derleme

Dağıtılabilir bir MCPB paketi oluşturmak için:

npm run mcpb:bundle

Bu komut şunları yapar:

1. Sürümü package.json'ten manifest.json'ya senkronize eder
2. Eski .mcpb dosyalarını kaldırır
3. TypeScript projesini derler
4. dist/ ve node_modules/ dosyalarını bir .mcpb dosyasına paketler
5. devDependencies'i kaldırmak için mcpb clean çalıştırır (paketi ~47MB'den ~10MB'ye optimize eder)

Çıktı dosyası anki-mcp-server-X.X.X.mcpb olarak adlandırılır ve tek tıklamayla kurulum için dağıtılabilir.

Pakete Neler Dahil Edilir

MCPB paketi şunları içerir:

• Derlenmiş JavaScript (dist/ dizini - üç giriş noktasının tümünü içerir)
• Yalnızca üretim bağımlılıkları (node_modules/ - devDependencies mcpb clean tarafından kaldırılır)
• Paket meta verileri (package.json)
• Manifest yapılandırması (manifest.json - main-stdio.js kullanacak şekilde yapılandırılmıştır)
• Simge (icon.png)

Kaynak dosyalar, testler ve geliştirme yapılandırmaları .mcpbignore aracılığıyla otomatik olarak hariç tutulur.

Claude Desktop'ta Günlük Kaydı

Claude Desktop'ta bir MCPB uzantısı olarak çalışırken günlükler şuraya yazılır:

Günlük Konumu: ~/Library/Logs/Claude/ (macOS)

Günlükler birden çok dosyaya bölünmüştür:

• main.log - Genel Claude Desktop uygulama günlükleri
• mcp-server-Anki MCP Server.log - Bu uzantı için MCP protokol mesajları
• mcp.log - Tüm sunuculardan birleştirilmiş MCP günlükleri

Not: pino günlükçü çıktısı (sunucu kodundan INFO, ERROR, WARN mesajları) stderr'e gider ve MCP'ye özgü günlük dosyalarında görünür. Claude Desktop hangi günlük dosyasının hangi mesajları alacağını belirler, ancak genel olarak:

• Uygulama başlatma ve MCP protokol iletişimi → MCP'ye özgü günlük
• Sunucu iç günlük kaydı (pino) → Hem MCP'ye özgü günlük hem de bazen main.log

Günlükleri gerçek zamanlı görüntülemek için:

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

MCP Sunucusunda Hata Ayıklama

MCP sunucusunda MCP Inspector kullanarak ve IDE'nizden (WebStorm, VS Code vb.) bir hata ayıklayıcı ekleyerek hata ayıklayabilirsiniz.

HTTP Modu için Not: MCP Inspector ile HTTP modunu (Akışkan HTTP) test ederken CORS hatalarını önlemek için "Bağlantı Türü: Proxy Üzerinden" kullanın.

Adım 1: MCP Inspector'da Hata Ayıklama Sunucusunu Yapılandırma

mcp-inspector-config.json zaten bir hata ayıklama sunucusu yapılandırması içerir:

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

Adım 2: Hata Ayıklama Sunucusunu Başlatın

MCP Inspector'ı hata ayıklama sunucusuyla çalıştırın:

npm run inspector:debug

Bu, sunucuyu 9229 portunda Node.js hata ayıklama etkinleştirilmiş şekilde başlatacak ve ilk satırda yürütmeyi duraklatacaktır.

Adım 3: IDE'nizden Hata Ayıklayıcıyı Bağlayın

WebStorm

1. Run → Edit Configurations bölümüne gidin
2. Yeni bir Attach to Node.js/Chrome yapılandırması ekleyin
3. Portu 9229 olarak ayarlayın
4. Bağlamak için Debug düğmesine tıklayın

VS Code

1. Hata Ayıklama panelini açın (Ctrl+Shift+D / Cmd+Shift+D)
2. Debug MCP Server (Attach) yapılandırmasını seçin
3. Bağlamak için F5'e basın

Adım 4: Kesme Noktaları Belirleyin ve Hata Ayıklayın

Bağlandıktan sonra şunları yapabilirsiniz:

• TypeScript kaynak dosyalarınızda kesme noktaları belirleyin
• Kod yürütme adımlarını ilerleyin
• Değişkenleri ve çağrı yığınını inceleyin
• İfadeleri değerlendirmek için hata ayıklama konsolunu kullanın

Hata ayıklayıcı, derlenmiş JavaScript yerine orijinal TypeScript kodunda hata ayıklamanıza olanak tanıyan kaynak haritalarıyla çalışacaktır.

Claude Desktop ile Hata Ayıklama

Node.js hata ayıklayıcısını etkinleştirip IDE'nizi bağlayarak MCP sunucusunda Claude Desktop içinde çalışırken de hata ayıklayabilirsiniz.

Adım 1: Claude Desktop'ı Hata Ayıklama için Yapılandırın

Hata ayıklamayı etkinleştirmek için Claude Desktop yapılandırmanızı güncelleyin:

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

Önemli değişiklik: dist/main-stdio.js yolundan önce --inspect=9229 ekleyin

Hata ayıklama seçenekleri:

• --inspect=9229 - Hata ayıklayıcıyı hemen başlatır, engellemez (önerilir)
• --inspect-brk=9229 - Hata ayıklayıcı bağlanana kadar yürütmeyi duraklatır (başlangıç sorunlarını hata ayıklamak için)

Adım 2: Claude Desktop'ı Yeniden Başlatın

Yapılandırmayı kaydettikten sonra Claude Desktop'ı yeniden başlatın. MCP sunucusu artık 9229 portunda hata ayıklama etkinleştirilmiş şekilde çalışacaktır.

Adım 3: IDE'nizden Hata Ayıklayıcıyı Bağlayın

WebStorm

1. Run → Edit Configurations bölümüne gidin
2. + düğmesine tıklayın ve Attach to Node.js/Chrome seçeneğini belirleyin
3. Yapılandırın:
   • Name: Attach to Anki MCP (Claude Desktop)
   • Host: localhost
   • Port: 9229
   • Attach to: Node.js < 8 veya Chrome or Node.js > 6.3 (WebStorm sürümüne bağlı olarak)
4. OK düğmesine tıklayın
5. Bağlamak için Debug (Shift+F9) düğmesine tıklayın

VS Code

1. .vscode/launch.json dosyasına ekleyin:

{
  "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. Hata Ayıklama panelini açın (Ctrl+Shift+D / Cmd+Shift+D)
3. Attach to Anki MCP (Claude Desktop) seçeneğini seçin
4. Bağlamak için F5'e basın

Adım 4: Gerçek Zamanlı Hata Ayıklama

Bağlandıktan sonra şunları yapabilirsiniz:

• TypeScript kaynak dosyalarınızda kesme noktaları belirleyin (ör. src/mcp/primitives/essential/tools/create-model.tool.ts)
• Claude Desktop'ı normal şekilde kullanın - araçlar çağrıldığında kesme noktaları tetiklenecektir
• Kod yürütme adımlarını ilerleyin
• Değişkenleri ve çağrı yığınını inceleyin
• Hata ayıklama konsolunu kullanın

Örnek: create-model.tool.ts dosyasında 119. satıra bir kesme noktası belirleyin ve ardından Claude'dan yeni bir model oluşturmasını isteyin. Hata ayıklayıcı kesme noktanızda duraklayacaktır!

Not: Hata ayıklayıcı, Claude Desktop çalıştığı sürece bağlı kalır. Claude Desktop'ı yeniden başlatmadan istediğiniz zaman bağlantıyı kesebilir/yeniden bağlayabilirsiniz.

Derleme Komutları

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 Paket Testi (Yerel)

Yayınlamadan önce npm paketini yerel olarak test edin:

# 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

Nasıl çalışır:

• npm pack, npm publish'in oluşturacağıyla aynı olan bir .tgz dosyası oluşturur
• .tgz adresinden yükleme, kullanıcıların npm install -g ankimcp adresinden aldıklarını simüle eder
• Bu, npm'e yayınlamadan önce tam kullanıcı deneyimini test etmenizi sağlar

Test Komutları

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)

Test Kapsamı

Proje, aşağıdakiler için minimum %70 kapsam eşiklerini korur:

• Dallar
• Fonksiyonlar
• Satırlar
• İfadeler

Kapsam raporları coverage/ dizininde oluşturulur.

Sürümleme

Bu proje, 1.0 öncesi geliştirme yaklaşımıyla Semantik Sürümleme izler:

• 0.x.x - Beta/Geliştirme sürümleri (mevcut aşama)

  • 0.1.x - Hata düzeltmeleri ve yamalar
  • 0.2.0+ - Yeni özellikler veya küçük iyileştirmeler
  • 0.x sürümlerinde kırıcı değişiklikler kabul edilebilir

• 1.0.0 - İlk kararlı sürüm

  • API kararlı ve test edildiğinde yayınlanacaktır
  • Kırıcı değişiklikler büyük sürüm artışları gerektirecektir (2.0.0, vb.)

Mevcut Durum: 0.27.0 - Aktif beta geliştirme. Son özellikler arasında koleksiyon genelinde inceleme analizi (deck atlandığında review_stats artık tüm destelerde toplar), model alan yönetimi (addModelField, removeModelField, renameModelField, repositionModelField), toplu not oluşturma (addNotes), entegre ngrok tünelleme (--ngrok bayrağı), medya dosyası yönetimi, model/şablon yönetimi ve kapsamlı deste istatistikleri yer alır. API'ler geri bildirim ve testlere göre değişebilir.

MCPB spesifikasyon gelişimi

Bu proje, hala gelişmekte olan Anthropic'in MCPB paket spesifikasyonunu hedefler. Spesifikasyonu https://github.com/modelcontextprotocol/mcpb adresinde takip ediyoruz ve uyumlu kalmak için kırıcı değişiklikler getirebiliriz. Kırıcı değişikliklere 0.x.x sürümleme şeması altında izin verilir.

Benzer Projeler

Anki MCP entegrasyonlarını keşfediyorsanız, bu alandaki diğer projeler şunlardır:

scorzeth/anki-mcp-server

• Durum: Görünüşe göre terk edilmiş (son güncelleme yok)
• Anki MCP entegrasyonunun erken uygulaması

nailuoGG/anki-mcp-server

• Yaklaşım: Hafif, tek dosyalık uygulama
• Mimari: Tüm araçların tek dosyada olduğu prosedürel kod yapısı
• Uygun: Basit kullanım durumları, minimum bağımlılıklar

Bu projenin farkı:

• Kurumsal düzeyde mimari: Bağımlılık enjeksiyonu ile NestJS üzerine inşa edilmiştir
• Modüler tasarım: Her araç, net sorumluluk ayrımına sahip ayrı bir sınıftır
• Bakım kolaylığı: Mevcut koda dokunmadan yeni özelliklerle genişletmek kolaydır
• Test: %70 kapsam gereksinimi olan kapsamlı test paketi
• Tip güvenliği: Zod doğrulamalı katı TypeScript
• Hata yönetimi: Yararlı kullanıcı geri bildirimiyle sağlam hata yönetimi
• Üretime hazır: Uygun günlükleme, ilerleme raporlama ve MCPB paket desteği
• Ölçeklenebilirlik: Temel araçlardan karmaşık iş akışlarına kolayca büyüyebilir

Kullanım durumu: Gelişmiş Anki entegrasyonları oluşturmak için sağlam bir temele ihtiyacınız varsa veya işlevselliği önemli ölçüde genişletmeyi planlıyorsanız, bu projenin mimari yaklaşımı zaman içinde bakımı ve ölçeklendirmeyi kolaylaştırır.

Faydalı Bağlantılar

• Model Context Protocol Dokümantasyonu
• AnkiConnect API Dokümantasyonu
• Claude Desktop İndirme
• Masaüstü Uzantıları Oluşturma (Anthropic Blog)
• MCP Sunucuları Deposu
• NestJS Dokümantasyonu
• Anki Resmi Web Sitesi

Lisans ve Atıf

Bu proje MIT Lisansı altında lisanslanmıştır — tam metin için LICENSE dosyasına bakın.

Telif Hakkı © 2026 Anatoly Tarnavsky.

Üçüncü Taraf Atıfları

• Anki®, Ankitects Pty Ltd'nin tescilli ticari markasıdır. Bu proje resmi olmayan bir üçüncü taraf aracıdır ve Ankitects Pty Ltd ile bağlantılı, onaylanmış veya desteklenen bir proje değildir. Anki logosu, https://apps.ankiweb.net bağlantısıyla Anki'ye atıfta bulunmak için alternatif lisans altında kullanılmaktadır. Resmi Anki uygulaması için https://apps.ankiweb.net adresini ziyaret edin.

• Model Context Protocol (MCP), Anthropic'in açık standardıdır. MCP logosu, resmi MCP dokümantasyon deposundan alınmıştır ve MIT Lisansı altında kullanılmaktadır. MCP hakkında daha fazla bilgi için https://modelcontextprotocol.io adresini ziyaret edin.

• Bu, Anki ve MCP teknolojilerini birbirine bağlayan bağımsız bir projedir. Tüm ticari markalar, hizmet markaları, ticari unvanlar, ürün adları ve logolar ilgili sahiplerinin mülkiyetindedir.