ankimcp/anki-mcp-server

Anki MCP サーバー – 概要

Anki MCP サーバーは、Model Context Protocol（MCP）を実装したNode‑JSサービスです。AIアシスタント（Claude、Cursor、Cline、Zedなど）とAnki間隔反復アプリ（AnkiConnectプラグイン経由）の間に位置します。豊富な「ツール」セット（デッキ一覧、期限切れカード取得、ノート作成、メディアアップロード、Ankiのデスクトップウィンドウを操作するGUIコマンドなど）を公開することで、サーバーは言語モデルがあたかも対話型チューターのようにあなたの個人用フラッシュカードコレクションと対話できるようにします。

存在理由

• AI駆動の学習 – チャットを離れることなく、アシスタントにデッキのレビュー、新しいカードの生成、画像の追加を依頼できます。
• 標準化されたトランスポート – MCPは、多くのAIクライアント製品がすでに理解しているJSON‑over‑STDIOまたはHTTP APIを定義します。
• Ankiから分離 – サーバーはAnkiの外部で実行されるため、サブプロセスを起動できる、またはローカルWebサーバーを呼び出せるAIクライアントはすべて使用できます。

このリポジトリとアドオンの使い分け

• 最も簡単なオールインワン体験（HTTP、リモートトンネル、Node.js不要）には、AnkiMCPアドオン（Anki内にインストール）を使用します。
• 次のニーズがある場合は、このスタンドアロンサーバーを使用します：
  • STDIOトランスポート – Claude Desktop、Cursor、Cline、Zedなどで必要。
  • MCPBバンドル – Claude Desktop用のワンクリックインストーラー。

---

コア機能（READMEに記載）

カテゴリ	ツール（抜粋）	機能
復習と学習	sync, get_due_cards, present_card, rate_card, forgetCards, setDueDate	AnkiWebと同期、復習予定のカード取得、カード表示、評価記録、スケジュールの手動調整。
デッキ管理	listDecks, deckStats, createDeck, changeDeck	デッキ一覧、詳細統計、新しいデッキ作成（2階層階層対応）、デッキ間でのカード移動。
ノート管理	addNote, addNotes, findNotes, notesInfo, updateNoteFields, deleteNotes	単一または一括ノート作成、Ankiクエリ構文での検索、ノートフィールドの読み取り・編集、ノート削除。
タグ管理	getTags, addTags, removeTags, replaceTags, clearUnusedTags	タグの取得、追加、削除、名前変更、クリーンアップ。
メディア管理	getMediaFilesNames, retrieveMediaFile, storeMediaFile, deleteMediaFile	メディアファイルの一覧取得、ダウンロード（base64）、アップロード（パス、URL、base64）、削除。READMEでは速度のためファイルパスまたはURLの使用を推奨。
モデル/テンプレート管理	modelNames, modelFieldNames, modelStyling, modelTemplates, createModel, updateModelStyling, addModelField …	ノートタイプ（モデル）、フィールド、CSSスタイル、カードテンプレートの検査、作成、変更。
統計	collection_stats, review_stats	コレクション全体の統計と復習履歴の分析。
GUIツール（復習用ではない）	guiBrowse, guiAddCards, guiEditNote, guiDeckOverview, guiCurrentCard, guiUndo	Ankiのデスクトップウィンドウを開いたりUIを操作するコマンド。インタラクティブなワークフローに有用。

サーバーは現在53ツール（基本42 + GUI 11）を提供しています。各ツールはMCP JSONプロトコルを介して呼び出され、AIが解析してアクションを起こせる構造化データを返します。

---

実行方法

1. 前提条件 – Ankiをインストールし、AnkiConnectプラグインを追加し、Node.js 22.12以上が必要です。
2. インストールオプション
   • npm（グローバルまたはnpx） – npm install -g @ankimcp/anki-mcp-server を実行してから ankimcp を実行するか、npx @ankimcp/anki-mcp-server でオンザフライ実行。
   • MCPBバンドル – GitHubリリースページから .mcpb ファイルをダウンロードし、Claude Desktopにインストール（ドラッグ＆ドロップまたは設定 → 拡張機能）。
   • ソースから – クローン、npm install、npm run build。
3. トランスポートを選択
   • STDIO – デスクトップAIクライアントに最適。クライアントがサーバーをサブプロセスとして起動（ankimcp --stdio）。Claude Desktop、Cursor、Cline、Zed、opencode用の設定スニペットが提供されています。
   • HTTP – ローカルWebサーバーを実行（ankimcp はデフォルトで localhost:3000）。WebベースのAIツールに有用。
4. リモートアクセス（AIがクラウドで動作する場合）
   • トンネル（推奨） – ankimcp --tunnel で管理されたWebSocketトンネルサービスに接続し、OAuthデバイスフローで認証、ChatGPTやClaude.aiなどに渡せる公開URLが取得できます。
   • ngrok – 代替の認証なしオプション（READMEには詳しくありません）。

---

一般的なユースケースの流れ（READMEの例より）

1. デッキを復習 – AIが sync、次に get_due_cards（デッキでフィルタリング可能）を送信し、返されたカードを present_card で反復処理、各回答後に rate_card を呼び出します。
2. 新しいカードを作成 – AIが modelNames でノートタイプを選択、必要に応じてRTLアラビア語用に createModel、次に addNotes で必要なフィールドを追加。
3. 画像を追加 – AIが storeMediaFile でローカルファイルをアップロードし、guiSelectedNotes + notesInfo で現在選択中のノートを取得、updateNoteFields で先頭フィールドを更新して <img> タグを埋め込み。

---

誰に役立つか？

• フラッシュカードをその場で取得・説明・編集できる対話型チューターを求める学習者。
• 個人のAnkiコレクションへのプログラムによるアクセスが必要なカスタムAIエージェントを開発する開発者。
• LLM駆動スクリプトによる一括ノート作成やメディア管理を自動化したい教育者。

---

制限と注意点（READMEによる）

• サーバーはAnkiConnectが必要 – Ankiと直接通信しません。
• 一部のツール（例：forgetCards, setDueDate）はレビューを記録せずにスケジュールを変更するため、長期統計に影響する可能性があります。
• リモートアクセスには管理されたトンネル（推奨）または別のトンネルソリューションが必要です。Ankiを直接インターネットに公開することは推奨されません。
• ほとんどのユーザーにとって、AnkiMCPアドオンの方が簡単です。このリポジトリは主にSTDIOまたはMCPBバンドルが必要な方向けです。

---

クイックスタート（npx経由のSTDIO）

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

上記のJSONをAIクライアントの適切な設定ファイル（例：Cursorの場合は ~/.cursor/mcp.json）に配置すると、クライアントがサーバーを自動的に起動します。

---

要約： Anki MCP サーバーは、Nodeベースのブリッジであり、最新のLLM搭載アシスタントが明確に定義されたプロトコルを通じてAnkiフラッシュカードを読み取り、編集、管理できるようにし、ローカルのSTDIOとリモートのHTTP/トンネル接続の両方をサポートします。