Anki MCP Server

Anki MCP Server

重要

ほとんどの環境では、AnkiMCP addonをおすすめします。

このアドオン（GitHub）は、MCP サーバーをAnki内で直接実行します。Node.jsのインストールも、AnkiConnectの設定も、別プロセスを起動し続ける必要もありません。コード 124672614 でインストールしてAnkiを再起動すれば、Ankiを起動するたびにサーバーが立ち上がります。ローカルHTTPアクセスと、組み込みトンネルを介したリモートアクセスに対応しています。

次の用途には、このリポジトリが適しています。

• STDIOトランスポート — Claude Desktop、Claude Code、Cursor、またはサーバーをサブプロセスとして起動するクライアント
• MCPBバンドル — Claude Desktop向けのワンクリック .mcpb インストール

HTTP、トンネル、またはウェブベースのクライアント（claude.ai、ChatGPT）には、アドオンのほうが簡単で、より充実したサポートを受けられます。

このリポジトリは非推奨にはなりません。同じankimcp.aiプロジェクトの一部として、アドオンとともに保守・リリースを継続します。

Ankiの間隔反復型フラッシュカードアプリケーションをAIアシスタントから操作できるようにする、Model Context Protocol（MCP）サーバーです。

家庭教師がそばにいるように、自然言語でやり取りしながらAnkiを活用できます。AIアシスタントは質問と回答を提示するだけではありません。概念を説明し、学習をより魅力的で人間らしいものにし、背景情報を補い、あなたの学習スタイルに合わせて対応します。学習中にノートを作成・編集できるため、学習セッションを動的な会話に変えられます。今後、さらに機能を追加予定です。

使用例とチュートリアル

Claude DesktopでこのMCPサーバーを使用するための詳しいガイド、実例、手順を追ったチュートリアルについては、次のサイトをご覧ください。

ankimcp.ai — 実践的な例とユースケースを含む完全なドキュメント

レビュアー向けセットアップガイドやAnkiのサンプルデッキなど、補足ドキュメントについては docs/をご覧ください。

使用例

このサーバーで利用できるツールの一連の流れを示す、代表的なプロンプトを3つ紹介します。

1. 「スペイン語のデッキの復習を手伝ってください。」 — アシスタントがAnkiWebとの同期を提案し（sync）、期限の来たカードを取得し（デッキで絞り込んだget_due_cards）、各カードを提示して（present_card）、評価を記録します（rate_card）。あなたに合わせた解説を交えた、自然な学習会話ができます。

2. 「右から左に表示するスタイルで、アラビア語の単語カードを10枚作成してください。」 — アシスタントがノートタイプを一覧表示し（modelNames）、必要に応じてカスタムの右から左に表示するモデルを作成し（右から左に表示するCSS用のcreateModel + updateModelStyling）、その後カードをまとめて作成します（addNotes）。

3. 「Downloadsフォルダーにあるこの画像を、選択中のノートの表面にインポートしてください。」 — アシスタントがローカルファイルをアップロードし（ファイルパスを指定したstoreMediaFile）、ブラウザーで現在選択されているノートを読み込み（guiSelectedNotes + notesInfo）、<img>タグを使って表面のフィールドを更新します（updateNoteFields）。

利用可能なツール

このサーバーは53個のMCPツールを提供します。日常的なAnki操作に役立つ基本ツールが42個、ノートの編集・作成ワークフローでAnkiのデスクトップインターフェースを操作するGUIツールが11個です。

基本ツール

復習と学習

• sync - AnkiWeb と同期して最新データを取得し、変更を送信します
• get_due_cards - 復習期限のカードを取得します。オプションでデッキによる絞り込みができます（include_answer: true を指定しない限り、回答は省略されます。デフォルトは false です）
• get_cards - 状態（due、new、learning、suspended、buried）とデッキで柔軟に絞り込んでカードを取得します（include_answer: true を指定しない限り、回答は省略されます。デフォルトは false です）
• present_card - 質問面／表面を表示して、復習用にカードを提示します
• rate_card - カードの成績（Again、Hard、Good、Easy）を評価し、次回の復習をスケジュールします
• forgetCards - 復習を記録せずに、カードを新規状態にリセットし、スケジュールを破棄します
• setDueDate - 復習を記録せずに、N 日後に復習期限となるようカードを再スケジュールします（"0"、"3-7"、"1!"）
• areSuspended - 変更を加えずに、1 枚以上のカードの停止状態を確認します
• suspend - カードを停止し、再開されるまで復習対象から除外します
• unsuspend - カードの停止を解除し、通常の復習に戻します

注： forgetCards と setDueDate は復習を記録せずにスケジュールを変更するため、rate_card とは異なります。カードの回答ではなくスケジュールが間違っている場合に使用してください。カードをさらに先送りするために Again と評価すると、実際の失念として記録され、易しさ係数が下がり、今後のスケジュールと統計の両方に恒久的な偏りが生じます。forgetCards は間隔をリセットしてカードを最初からやり直し、setDueDate はカードの履歴を維持したまま次回の復習日だけを変更します。

注： カードの front／back の内容は、それぞれのカードのテンプレートに基づいて描画されるため（Anki の表示と同様）、反転カードや穴埋めカードも正しい方向で表示されます。カードテンプレートに追加された静的テキストも出力に含まれます。

デッキ管理

• listDecks - すべてのデッキを一覧表示します。オプションでデッキごとの学習キュー統計も表示できます
• deckStats - 1 つのデッキの包括的な統計情報（学習キュー、正確なカード状態の件数、易しさ／間隔の分布）を取得します
• createDeck - 空の新しいデッキを作成します（Parent::Child に対応。最大 2 階層）
• changeDeck - カードを別のデッキに移動します（存在しない場合は作成されます）

注： デッキの統計には 2 種類あります。counts ブロック（および listDecks が報告するすべての情報）は Anki のデッキブラウザーに準じており、各デッキの 1 日あたりの新規／復習上限 を適用した、今日が復習期限の カード数を示します。停止中および埋め込みカードは除外されます。そのため、review は「成熟したカード」を意味せず、other の区分は単なる計算上の残り（主に今日が復習期限ではない復習カードと、1 日あたりの上限を超えた新規カード）です。状態ごとの正確な合計を確認するには、deckStats／collection_stats の states ブロックを使用してください。これは Anki の検索機能を使って new、learning、review、suspended、buried をカウントし、復習期限と 1 日あたりの上限を無視します。

ノート管理

• addNote - 指定したフィールドとタグを持つノートを 1 件作成します
• addNotes - デッキとモデルを共有するノートを最大 100 件まとめて作成します（一部成功に対応）
• findNotes - Anki のクエリ構文（deck:、tag:、is:due など）を使用してノートを検索します
• notesInfo - ノートの詳細情報（フィールド、タグ、ノートタイプ、カード ID。CSS は modelStyling から取得）を取得します
• 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 - 既存のノートタイプのフィールド名を変更します（Anki はカードテンプレート内の旧名への参照を書き換えます）
• 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（グローバルまたは npx）

サーバーをインストールする汎用的な方法で、直接起動するあらゆる MCP クライアントに適しています。

ankimcp コマンドを実行するクライアント向けにグローバルにインストールします:

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

または、インストール不要でオンデマンドに実行します:

npx @ankimcp/anki-mcp-server

MCPB バンドル（Claude Desktop に推奨）

Claude Desktop にこの MCP サーバーをインストールする最も簡単な方法です。

1. Releases ページから最新の .mcpb バンドルをダウンロードします
2. Claude Desktop で拡張機能をインストールします。
   • 方法 1：Settings → Extensions に移動し、.mcpb ファイルをドラッグ＆ドロップします
   • 方法 2：Settings → Developer → Extensions → Install Extension に移動し、.mcpb ファイルを選択します
3. 必要に応じて AnkiConnect の URL を設定します（デフォルトは http://localhost:8765 です）
4. Claude Desktop を再起動します

これで完了です。このバンドルには、サーバーをローカルで実行するために必要なものがすべて含まれています。

Anthropic MCP Directory のレビュアー向け： サンプルデッキがあらかじめ用意された、ゼロから連携までの手順は docs/reviewer-setup.md にあります。

ソースからインストール（開発用）

開発または高度な使用向けです（テストスイートの実行には Node.js 24.9 以降が必要です。npm のテストスクリプトは require(esm) を介して ESM 専用の NestJS 12 パッケージを読み込みますが、Jest がこれをサポートしているのはそのバージョン以降のためです。サーバーの使用時の要件は引き続き 22.12.0 以降です）。

npm install
npm run build

AI クライアントとの接続

AI アシスタントがこのサーバーに接続する方法は、アシスタントの実行場所によって 2 通りあります。

• ローカル — サーバーは AI クライアント（Claude Desktop、Cursor、Cline、Zed、またはローカルのブラウザーセッション）と同じマシン上で実行されます。デスクトップ MCP クライアントには STDIO、ローカルのウェブベースのツールには HTTP を使用します。
• リモート — ホストされた／リモートの AI（例：クラウド上の ChatGPT または Claude.ai）が、ローカルマシン上で実行中の Anki に接続する必要がある場合です。管理された トンネル（✅ 推奨 — 認証あり）、または認証なしの軽量な代替手段として ngrok を使用します。

ローカル

サーバーは AI クライアントと同じコンピューター上で実行され、localhost の AnkiConnect と通信します。

STDIO（ローカル連携の主な方法）

STDIO は、ローカルのデスクトップ MCP クライアント（Claude Desktop、Cursor IDE、Cline、Zed Editor、opencode など）で標準的に使用されるトランスポートです。クライアントはサーバーをサブプロセスとして起動し、標準入出力を介して通信します。

対応クライアント：

• Claude Desktop
• Cursor IDE - AI 搭載のコードエディター
• Cline - AI アシスタンス用の VS Code 拡張機能
• Zed Editor - 高速でモダンなコードエディター
• opencode - ターミナル上で動作する AI コーディングエージェント
• STDIO トランスポートに対応するその他の MCP クライアント

Claude Desktop では、MCPB バンドルを使うのが最も簡単です。その他のクライアントでは、--stdio フラグを指定して npm パッケージを設定してください。

設定 — 次のいずれかの方法を選択してください：

方法 1：npx を使用（推奨 — インストール不要）

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

方法 2：グローバルインストールを使用

まず、グローバルにインストールします。

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

次に、設定します。

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

opencode は独自の形式を使用します。サーバーは mcp の下に配置し、コマンドは単一の配列に、環境変数は environment の下に記述します。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "anki-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "enabled": true,
      "environment": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

設定ファイルの場所：

• Cursor IDE：~/.cursor/mcp.json（macOS/Linux）または %USERPROFILE%\.cursor\mcp.json（Windows）
• Cline：VS Code の設定 UI からアクセスできます
• Zed Editor：拡張機能マーケットプレイスから MCP 拡張機能としてインストールします
• opencode：プロジェクトのルートにある opencode.json、またはグローバル設定の ~/.config/opencode/opencode.json

クライアント固有の機能やトラブルシューティングについては、ご利用の MCP クライアントのドキュメントを参照してください。また、ビルド済みの dist/main-stdio.js を直接指定する設定については、Claude Desktop に接続も参照してください。

HTTP（ローカルのウェブベースAI）

HTTP モードでは、MCP Streamable HTTP プロトコルを使用するローカルウェブサーバーとしてサーバーを実行します。ウェブベースのAIツールがあなたのマシンを指定したときに接続するトランスポートであり、リモートの各オプションで外部に公開されるものでもあります。HTTP モード単独では、localhost のみをバインドします。

localhost 以外にバインドする場合 --host 0.0.0.0 を渡す（またはリバースプロキシ／パブリックドメインの背後で実行する）場合、DNS リバインディング対策として、デフォルトではサーバーはループバックの Host ヘッダーのみを受け入れます。クライアントが使用するホスト名を 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：グローバルインストールを使用する

# 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

クラウドでホストされているAIからローカルのHTTPサーバーにアクセスできるようにするには、以下のリモートオプションのいずれかを使用してください。

リモート

ホスト型／リモートAI（ChatGPT やクラウド上で動作する Claude.ai など）は、localhost に直接アクセスできません。これらのオプションを使うと、リモートアシスタントが接続できるように、ローカルの Anki をインターネットに公開できます。

トンネル（✅ 推奨）

推奨されるリモート接続経路 — 認証済みかつ安全。 生のパブリックポートとは異なり、トンネルモードではログイン（OAuth 2.0 デバイスフロー）が必要なため、URL を推測した誰もがエンドポイントにアクセスできるわけではありません。

トンネルモードでは、独自のトンネルを運用することなく、Web ベースの AI アシスタントがローカルの Anki にアクセスできます。サーバーはマネージド AnkiMCP トンネルサービス（wss://tunnel.ankimcp.ai）へ WebSocket 経由で外向きに接続し、パブリック URL が割り当てられます。認証は組み込まれています — ngrok アカウントや別途のトンネルプロセスは不要で、ログインは一度だけです。

ログイン（OAuth デバイスフロー）:

トンネルモードは OAuth 2.0 デバイス認可グラントを使用します。ログインすると、コードがすでに 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

トンネルを開始する:

# 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 は自動的に先にログインフローを開始し、その後トンネルへ進みます。この自動ログインには対話的なターミナルが必要です — stdout が TTY でない場合（systemd、ヘッドレス Docker、CI）、サーバーは即座に失敗し、先に ankimcp --login を実行するよう求められます。接続されると、パブリックトンネル URL が表示されます。Ctrl+C を押すと切断されます。その URL を AI アシスタントと共有してください。

トンネルモードの環境変数:

変数	説明	デフォルト
TUNNEL_SERVER_URL	トンネルサーバーの WebSocket URL（--tunnel/--login フラグの値がこれを上書きします）	wss://tunnel.ankimcp.ai
TUNNEL_AUTH_CLIENT_ID	デバイスフロー用の OAuth クライアント ID。上級者向け — セルフホストのトンネル/認証サービスを指定する場合にのみ必要です。	（組み込み）

デバイスフローの認証エンドポイント（/auth/device、/auth/token）は TUNNEL_SERVER_URL から導出されるため、--tunnel（または TUNNEL_SERVER_URL）を別のホストに向けると、認証もそのホストに移動します。

仕組み: トンネルモードは、インメモリトランスポート（TunnelTransport）の背後で MCP サーバーをインプロセスで実行します。このトランスポートが MCP サーバーを所有し、中継された各リクエストボディをレスポンスに変換します。そして TunnelClient が WebSocket 経由でそれをリモートトンネルサービスにブリッジします — MCP リクエストを中に入れ、レスポンスを外に出します。AnkiConnect には依然としてお使いのローカルマシン上でのみ到達します。

プロトコルリビジョン: トンネルは MCP サーバーをインプロセスで接続するため、トンネルモードは MCP プロトコルの 2025 リビジョンのみを提供します。一方、STDIO モードと HTTP モードは 2025 と新しい 2026-07-28 リビジョンの両方を提供します。どのツールもどちらでも同じように動作します — ただし、2026-07-28 のみに対応するクライアントは、トンネル経由ではプロトコルバージョンエラーで拒否されます。そのクライアントには STDIO モードまたは HTTP モードを実行してください。

ngrok（認証なしの代替手段）

マネージドトンネルのアカウントを作成せずに、ローカル HTTP モードを一般公開したい場合は、組み込みの --ngrok フラグで ngrok のサブプロセス（src/services/ngrok.service.ts）を起動し、起動バナーに公開 URL を表示できます。

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

この方法は認証されません。URL を知っている人は誰でも Anki にアクセスできるため、Tunnel より安全性が低くなります。ngrok エンドポイントを自分で管理する特別な理由がない限り、Tunnel をお使いください。（ngrok のグローバルインストールと authtoken が必要です。）

--ngrok フラグは --host-header=rewrite を付けて ngrok を起動するため、転送前に ngrok が上流の Host を localhost に書き換えます。これにより、公開された *.ngrok ドメインを ALLOWED_HOSTS に追加しなくても、リクエストがループバック Host 許可リスト内に収まります（DNS リバインディング保護を参照）。代わりに 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 <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

読み取り専用モード（すべてのモード）

--read-only フラグ（または READ_ONLY=true）を指定すると、ノートの内容、デッキ、タグ、メディア、ノートタイプの変更と、カードの手動再スケジュールがブロックされます。有効にすると、次のようになります。

• すべての読み取り操作は通常どおり動作します（デッキの閲覧、カードの表示、ノートの検索）
• 次の変更は引き続き許可されます。復習中のカードの評価（rate_card）、カードの停止／停止解除（suspend、unsuspend）、AnkiWeb との同期（sync）、Anki のウィンドウを操作する GUI ツール（guiBrowse、guiDeckOverview、…）
• コンテンツの変更はブロックされます（addNote、deleteNotes、createDeck、updateNoteFields など）。ただし、すでに存在するデッキに対する createDeck は、何も書き込まないため成功します
• 手動での再スケジュールはブロックされます。forgetCards（新規カードにリセット）と setDueDate が対象です
• guiUndo はブロックされます。コレクションへの変更を元に戻す可能性があるためです
• guiAddCards と guiEditNote はブロックされます。開いたダイアログで追加または保存したノートがコレクションに書き込まれるためです
• コンテンツを誤って変更せずに 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 クライアントの設定で有効にできます。

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

Claude Desktop に接続する（ローカルモード）

次のいずれかの方法で、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	AnkiConnect で設定されている場合の API キー	-
ANKI_CONNECT_TIMEOUT	リクエストのタイムアウト（ミリ秒）	5000
READ_ONLY	読み取り専用モードを有効にします（true または 1）	false
PORT	HTTP モード：待ち受けるポート（--port フラグが優先されます）	3000
HOST	HTTP モード：バインドするアドレス（--host フラグが優先されます）	127.0.0.1
ALLOWED_HOSTS	HTTP モード：ループバック以外に許可する追加の Host ヘッダー値（ホスト名をカンマ区切りで指定）。LAN／パブリックアドレスにバインドする場合や、リバースプロキシ経由で実行する場合に必要です。HTTP モードの設定を参照してください。	ループバックのみ
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	トンネルサーバーの WebSocket URL（トンネルモードのみ）	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" - Spanish デッキにある、verb タグ付きのノート（AND）
• "deck:Spanish OR deck:French" - いずれかのデッキにあるノート

重要事項

CSS と HTML の処理

• notesInfo ツールは各ノートのノートタイプ名を返します。CSS 自体は modelStyling から取得します。
• updateNoteFields ツールはフィールド内の HTML コンテンツに対応しており、CSS スタイルを保持します。
• 各ノートモデルには独自の CSS スタイルがあるため、モデル固有の CSS を取得するには modelStyling を使用してください。

更新時の警告

⚠️ 重要：updateNoteFields を使用している間は、Anki のブラウザーでノートを表示しないでください。表示しているとフィールドが正しく更新されません。更新前にブラウザーを閉じるか、別のノートに切り替えてください。詳しくは既知の問題を参照してください。

削除時の安全対策

deleteNotes ツールでは、誤削除を防ぐために明示的な確認（confirmDeletion: true）が必要です。ノートを削除すると、関連するすべてのカードも完全に削除されます。

セキュリティ

メディアファイルのパスと URL の検証

メディアツール（storeMediaFile、retrieveMediaFile、deleteMediaFile）とupdateNoteFieldsの音声／画像フィールドには、プロンプトインジェクションによる不正利用を防ぐセキュリティ検証が組み込まれています。

• ファイルパスからのインポートは、メディアファイルの種類（画像、音声、動画）のみに制限されています。MIME タイプに基づき、メディア以外のファイル（SSH 鍵、認証情報、シェル設定ファイルなど）は拒否されます。追加のファイルタイプを許可するにはMEDIA_ALLOWED_TYPESを設定し、インポート先を特定のディレクトリに制限するにはMEDIA_IMPORT_DIRを設定してください。
• URL からのインポートでは、SSRF 攻撃に対する検証が行われます。プライベートネットワーク（10.x、172.16.x、192.168.x）、ループバック（127.x）、リンクローカル（169.254.x）へのリクエストと、HTTP(S) 以外のスキームはブロックされます。特定のプライベートネットワークホストを許可するにはMEDIA_ALLOWED_HOSTSを設定してください。
• ファイル名は、パストラバーサルを防ぐためにサニタイズされます（例：../../のような並びは除去されます）。

これらの保護は、storeMediaFile、retrieveMediaFile、deleteMediaFile、およびupdateNoteFieldsの音声／画像フィールドに適用されます。

パストラバーサルの脆弱性は、Hideaki Takahashi によって報告されました。

DNS リバインディング対策（HTTP トランスポート）

HTTP モードで実行する場合、サーバーはリクエストごとにHostヘッダーを検証します。デフォルトでは、ポートにかかわらずループバックホスト（localhost、127.0.0.1、::1）のみが許可されます。Hostはブラウザーから送信できないヘッダーのため、悪意のあるウェブページが偽装することはできません。これにより、DNS リバインディングされたページが偽装したHostとOriginヘッダーなしでローカルサーバーにアクセスし、MCP ツールに到達する経路を遮断します。許可されていないHostは403で拒否されます。

0.0.0.0にバインドする場合、リバースプロキシの背後で実行する場合、またはパブリックトンネルのドメインを公開する場合は、ALLOWED_HOSTS（カンマ区切りのホスト名）を設定して、それらのホストを許可してください。ngrok でトンネリングする場合、サーバーは--host-header=rewriteを使用するため、アップストリームからは引き続きループバックのHostが確認されます。オプションの一覧については、HTTP モードの設定をご覧ください。

DNS リバインディングの脆弱性は、avishaigo-commits および yotampe-pluto によって報告されました。

プライバシーポリシー

この MCP サーバーはお使いのマシン上でローカルに実行され、テレメトリ、分析データ、使用状況データを収集しません。

ポリシー全文：https://ankimcp.ai/privacy/

• データ収集：サーバーは何も収集しません。AI アシスタントとローカルの AnkiConnect プラグインの間でリクエストを中継します。
• 使用状況／保存：サーバー側での保存はありません。すべてのフラッシュカードデータは、お使いのデバイス上の Anki に保存されます。
• 第三者との共有：ありません。サーバーは、設定した AnkiConnect URL（デフォルト：localhost）とのみ通信します。Anki に組み込まれている AnkiWeb の同期を有効にした場合、その同期は Anki のインストール環境と AnkiWeb の間で直接行われ、このサーバーの対象外です。
• 保持期間：該当しません。サーバー側でデータを保持しません。
• お問い合わせ先：[email protected]

既知の問題

既知の問題と制限事項の一覧については、ドキュメントをご覧ください。

既知の問題に関するドキュメント

重大な制限事項

ブラウザーで表示中のノートは更新に失敗します

⚠️ 重要：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 のようなバージョンマネージャーを使用できます。

開発

トランスポートモード

このサーバーは、個別のエントリーポイントを通じて、3 つの MCP トランスポートモードをサポートしています。

STDIO モード（デフォルト）

• Claude Desktop のようなローカル MCP クライアント向け
• 標準入力／出力を使用して通信します
• エントリーポイント：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/（ルートパス）

トンネルモード（管理された WebSocket トンネル）

• 認証機能を内蔵した、管理型 AnkiMCP トンネルサービス経由のウェブベース AI アシスタント向け
• MCP サーバーはインメモリトランスポートの背後でプロセス内実行されます。TunnelTransport が MCP サーバーを管理し、TunnelClient が WebSocket 経由でトンネルサービスに接続します
• プロトコル：2025 MCP リビジョンのみを提供します（STDIO と HTTP は 2026-07-28 も提供します）
• エントリーポイント：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（ウォッチモードで --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 - バインドアドレス（デフォルト：localhost のみを対象とする 127.0.0.1）
• ALLOWED_HOSTS - 組み込みのループバックホスト（localhost、127.0.0.1、::1）に加えて許可する Host ヘッダー値をカンマ区切りで指定します。ホスト名のみが対象で、ポートは区別されません。デフォルト：ループバックのみ。
• 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 リバインディング対策） — すべての HTTP リクエストには、許可リストに一致する Host ヘッダーが必要です。デフォルトでは、ポートにかかわらずループバックホスト（localhost、127.0.0.1、::1）のみが許可されます。Host はブラウザーで禁止されているヘッダーであるため、悪意のある Web ページが偽装することはできません。これにより、ページがリバインドされ、偽装した Host と Origin なしでサーバーにアクセスする DNS リバインディングの経路を遮断します。許可されていない Host は 403 で拒否されます。
• Origin ヘッダーの検証 — Origin／Referer が存在するものの許可されていないブラウザーリクエストは拒否されます。Origin がないリクエスト（curl、Postman、MCP-over-HTTP クライアント）は許可されます。リバインディングへの対策は Host の検証です。
• デフォルトでは localhost（127.0.0.1）にバインドします。
• 現在のバージョンでは認証はありません（OAuth のサポートを予定しています）。

HTTP モードを localhost の外部に公開する場合 — LAN／パブリックアドレスにバインドする場合、またはサーバーをリバースプロキシやパブリックドメインの背後に置く場合は、クライアントが使用するホスト名を ALLOWED_HOSTS に必ず設定してください。設定しない場合、ループバック以外からのすべてのリクエストが 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

ALLOWED_HOSTS を設定せずに 0.0.0.0／:: にバインドすると、ループバックの Host ヘッダーのみが許可されることを示す起動時警告がサーバーのログに記録されます。

Docker／リバースプロキシ／パブリックドメイン： 同じルールが適用されます。Docker では、通常、コンテナーに公開されたホスト名またはプロキシの Host を使ってリクエストが届くため、それに応じて ALLOWED_HOSTS を設定してください。リバースプロキシ（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/ ディレクトリ。3 つすべてのエントリーポイントを含みます）
• 本番用の依存関係のみ（node_modules/。mcpb clean によって devDependencies は削除されます）
• パッケージのメタデータ（package.json）
• マニフェストの設定（manifest.json。main-stdio.js を使用するよう設定されています）
• アイコン（icon.png）

ソースファイル、テスト、開発用設定は .mcpbignore によって自動的に除外されます。

Claude Desktop でのログ記録

Claude Desktop で MCPB 拡張機能として実行する場合、ログは以下に書き込まれます。

ログの場所: ~/Library/Logs/Claude/ (macOS)

ログは複数のファイルに分かれています。

• main.log - Claude Desktop アプリケーション全般のログ
• mcp-server-Anki MCP Server.log - この拡張機能の MCP プロトコルメッセージ
• mcp.log - すべてのサーバーからの MCP ログを統合したもの

注意: pino ロガーの出力 (サーバーコードからの 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 Inspector を使用し、IDE (WebStorm、VS Code など) からデバッガーをアタッチすることで、MCP サーバーをデバッグできます。

HTTP モードに関する注意: MCP Inspector で HTTP モード (Streamable HTTP) をテストする場合は、CORS エラーを避けるために「Connection Type: Via Proxy」を使用してください。

ステップ 1: MCP Inspector でデバッグサーバーを構成する

mcp-inspector-config.json には、デバッグサーバーの構成がすでに含まれています:

{
  "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: デバッグサーバーを起動する

デバッグサーバーを指定して MCP Inspector を実行します:

npm run inspector:debug

これにより、ポート 9229 で Node.js デバッグが有効な状態でサーバーが起動し、最初の行で実行が一時停止します。

ステップ 3: IDE からデバッガーをアタッチする

WebStorm

1. Run → Edit Configurations に移動します
2. 新しい Attach to Node.js/Chrome 構成を追加します
3. ポートを 9229 に設定します
4. Debug をクリックしてアタッチします

VS Code

1. デバッグパネルを開きます (Ctrl+Shift+D / Cmd+Shift+D)
2. Debug MCP Server (Attach) 構成を選択します
3. F5 を押してアタッチします

ステップ 4: ブレークポイントを設定してデバッグする

アタッチすると、以下のことができます。

• TypeScript ソースファイルにブレークポイントを設定する
• コードの実行をステップ実行する
• 変数とコールスタックを検査する
• デバッグコンソールを使用して式を評価する

デバッガーはソースマップで動作するため、コンパイルされた JavaScript ではなく、元の TypeScript コードをデバッグできます。

Claude Desktop でのデバッグ

Node.js デバッガーを有効にして IDE をアタッチすることで、Claude Desktop 内で実行されている MCP サーバーをデバッグすることもできます。

ステップ 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"
      }
    }
  }
}

主な変更点: dist/main-stdio.js へのパスの前に --inspect=9229 を追加します

デバッグオプション:

• --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. デバッグパネルを開きます (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 を通常どおり使用する。ツールが呼び出されるとブレークポイントに到達します
• コードの実行をステップ実行する
• 変数とコールスタックを確認する
• デバッグコンソールを使用する

例：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 は、npm publish で作成されるものと同一の .tgz ファイルを生成します
• .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％のカバレッジしきい値を維持しています。

• 分岐
• 関数
• 行
• 文

カバレッジレポートは coverage/ ディレクトリに生成されます。

バージョニング

このプロジェクトでは、1.0以前の開発方式でセマンティックバージョニングに従っています。

• 0.x.x - ベータ版／開発版（現在の段階）

  • 0.1.x - バグ修正とパッチ
  • 0.2.0+ - 新機能または軽微な改善
  • 破壊的変更は0.xバージョンで許容されます

• 1.0.0 - 最初の安定版リリース

  • API が安定し、テストが完了した時点でリリースされます
  • 破壊的変更にはメジャーバージョンの更新が必要です（2.0.0 など）

現在の状況：0.27.0 - ベータ開発を継続中です。最近追加された機能には、コレクション全体のレビュー分析（deck を省略すると review_stats がすべてのデッキを集計）、モデルフィールド管理（addModelField、removeModelField、renameModelField、repositionModelField）、ノートの一括作成（addNotes）、ngrok トンネリングの統合（--ngrok フラグ）、メディアファイル管理、モデル／テンプレート管理、包括的なデッキ統計などがあります。フィードバックやテストに応じて API が変更される場合があります。

MCPB 仕様の進化

このプロジェクトは、現在も進化中の Anthropic の MCPB バンドル仕様を対象としています。仕様は https://github.com/modelcontextprotocol/mcpb で追跡しており、準拠を維持するために破壊的変更を導入する場合があります。0.x.x のバージョニング方式では、破壊的変更が許容されています。

類似プロジェクト

Anki の MCP 統合を検討している方に向けて、この分野のほかのプロジェクトを紹介します。

scorzeth/anki-mcp-server

• 状況：放棄されたようです（最近の更新なし）
• Anki の MCP 統合の初期実装

nailuoGG/anki-mcp-server

• アプローチ：軽量な単一ファイルの実装
• アーキテクチャ：すべてのツールを1つのファイルにまとめた手続き型コード構成
• 適した用途：シンプルなユースケース、最小限の依存関係

このプロジェクトとの違い：

• エンタープライズ品質のアーキテクチャ：依存性注入を備えた NestJS を基盤に構築
• モジュール設計：各ツールが独立したクラスで、関心事が明確に分離されています
• 保守性：既存のコードに手を加えずに新機能を簡単に拡張できます
• テスト：カバレッジ70％の要件を満たす包括的なテストスイート
• 型安全性：Zod による検証を備えた厳格な TypeScript
• エラー処理：ユーザーに役立つフィードバックを提供する堅牢なエラー処理
• 本番環境対応：適切なロギング、進捗報告、MCPB バンドルのサポート
• スケーラビリティ：基本的なツールから複雑なワークフローまで、簡単に拡張できます

ユースケース：高度な Anki 統合を構築するための確かな基盤が必要な場合や、機能を大幅に拡張する予定がある場合、このプロジェクトのアーキテクチャアプローチなら、長期的な保守と拡張が容易になります。

便利なリンク

• Model Context Protocol のドキュメント
• AnkiConnect API のドキュメント
• Claude Desktop のダウンロード
• デスクトップ拡張機能の構築（Anthropic ブログ）
• MCP サーバーリポジトリ
• NestJS のドキュメント
• Anki 公式サイト

ライセンスと帰属表示

このプロジェクトは MIT ライセンスのもとでライセンスされています。全文についてはLICENSEをご覧ください。

Copyright © 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 ライセンスのもとで使用しています。MCP の詳細については、https://modelcontextprotocol.io をご覧ください。

• これは、Anki と MCP の技術をつなぐ独立したプロジェクトです。すべての商標、サービスマーク、商号、製品名、ロゴは、それぞれの所有者に帰属します。