Anki MCP

公式

AIアシスタントが間隔反復フラッシュカードアプリケーションAnkiと対話できるようにするMCPサーバー。

GitHub
539

Anki MCPで何ができますか？

  • 復習期限のカードを確認 — アシスタントに特定のデッキから期限が来たカードを取得してもらい、get_due_cards と present_card を使ってクイズ形式で復習してもらいます。
  • カードのパフォーマンスを評価 — アシスタントに回答の質（Again、Hard、Good、Easy）を記録させ、rate_card で復習スケジュールを再調整します。
  • カスタムフラッシュカードを作成 — アシスタントに createModel と updateModelStyling を使ってカスタムフィールドとRTLスタイルを持つ新しいノートタイプを構築させ、その後 addNotes でノートを一括追加します。
  • ノートの内容を管理 — findNotes でAnkiクエリ構文（deck:、tag:、is:due）を使ってノートを検索し、updateNoteFields でフィールドを更新します。
  • カードにメディアをインポート — アシスタントに storeMediaFile でローカルパスまたはURLから画像をアップロードさせ、guiSelectedNotes と updateNoteFields を使って選択したノートのフィールドに挿入します。
  • デッキとカードを整理 — createDeck でネストしたデッキ（Parent::Child）を作成し、changeDeck でカードをデッキ間で移動するか、suspend でカードを一時停止して復習時にスキップします。

ドキュメント

Anki MCP サーバー

Tests npm version

Anki + MCP Integration

AIアシスタントとAnkiを、Model Context Protocolを通じてシームレスに統合します

[!IMPORTANT] ほとんどのセットアップではAnkiMCPアドオンを推奨します。

このアドオン（GitHub）は、Anki内で直接MCPサーバーを実行します。Node.jsのインストールも、AnkiConnectの設定も、別途プロセスを起動しておく必要もありません。コード 124672614 でインストールし、Ankiを再起動するだけで、Ankiを開くたびにサーバーが起動します。ローカルHTTPアクセスと、内蔵トンネルによるリモートアクセスの両方に対応しています。

このリポジトリは、以下の特定のニーズがある場合に適しています：

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

HTTP、トンネル、またはWebベースのクライアント（claude.ai、ChatGPT）の場合は、アドオンの方がシンプルでサポートも充実しています。

このリポジトリは非推奨ではありません。同じankimcp.aiプロジェクトの一部として、アドオンと並行してメンテナンス・リリースを継続します。

AIアシスタントがAnki（間隔反復フラッシュカードアプリケーション）と対話できるようにするModel Context Protocol（MCP）サーバーです。

自然言語での対話を通じてAnki体験を変革します — まるで専属チューターがいるかのように。AIアシスタントは質問と回答を提示するだけでなく、概念を説明し、学習プロセスをより魅力的で人間らしいものにし、文脈を提供し、あなたの学習スタイルに適応します。その場でノートを作成・編集でき、学習セッションをダイナミックな会話に変えます。さらに多くの機能が近日公開予定です！

例とチュートリアル

このMCPサーバーをClaude Desktopで使用するための包括的なガイド、実践的な例、ステップバイステップのチュートリアルについては、以下を参照してください：

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

補足ドキュメントについてはdocs/を参照してください。レビューアーセットアップガイドとサンプルのAnkiデッキが含まれています。

使用例

このサーバーが有効にするツールフローを示す代表的な3つのプロンプト：

  1. 「スペイン語のデッキを復習するのを手伝って。」 — アシスタントがAnkiWebとの同期を提案し（sync）、期限切れのカードを取得し（get_due_cards、デッキフィルター付き）、各カードを提示し（present_card）、あなたの評価を記録します（rate_card）。あなたに合わせた説明付きの自然な学習会話。

  2. 「RTLスタイルのアラビア語ボキャブラリーカードを10枚作成して。」 — アシスタントがノートタイプを一覧表示し（modelNames）、必要に応じてカスタムRTLモデルを作成し（createModel + 右から左へのCSS用のupdateModelStyling）、カードを一括作成します（addNotes）。

  3. 「ダウンロードフォルダからこの画像を、選択中のノートの表面にインポートして。」 — アシスタントがローカルファイルをアップロードし（storeMediaFile、ファイルパス付き）、ブラウザから現在選択中のノートを読み取り（guiSelectedNotes + notesInfo）、<img> タグ付きで表面フィールドを更新します（updateNoteFields）。

利用可能なツール

このサーバーは53個のMCPツールを公開しています — 日常的なAnki操作のための42個の必須ツールと、ノート編集・作成ワークフローのためにAnkiデスクトップインターフェースを操作する11個のGUIツールです。

必須ツール

復習と学習

  • sync - AnkiWebと同期して最新データを取得し、変更をプッシュ
  • get_due_cards - 復習対象のカードを取得。デッキでフィルタリング可能（include_answer: true が指定されない限り回答は省略、デフォルトは false）
  • get_cards - 状態（期限切れ、新規、学習中、一時停止、埋没）とデッキによる柔軟なフィルタリングでカードを取得（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 - 単一デッキの包括的な統計を取得（学習キュー、実際のカード状態数、イーズ/間隔の分布）
  • createDeck - 新しい空のデッキを作成（Parent::Child をサポート、最大2レベル）
  • changeDeck - カードを別のデッキに移動（存在しない場合は作成）

注： デッキ統計には2種類あります。counts ブロック（および listDecks が報告するすべて）はAnkiのデッキブラウザを反映しています：今日期限のカードで、各デッキの毎日の新規/復習制限によって上限が設定され、一時停止・埋没カードは除外されます。つまり review は「成熟したカード」ではなく、other バケットは単なる算術的な残りです（主に今日期限ではない復習カードと、毎日の制限を超えた新規カード）。状態ごとの真の合計が必要な場合は、deckStats / collection_stats の states ブロックを使用してください。これはAnki検索を介して new、learning、review、suspended、buried をカウントし、期限日や毎日の制限を無視します。

ノート管理

  • addNote - 指定されたフィールドとタグで単一のノートを作成
  • 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：設定 → 拡張機能に移動し、.mcpb ファイルをドラッグ＆ドロップ
    • 方法2：設定 → 開発者 → 拡張機能 → 拡張機能をインストールに移動し、.mcpb ファイルを選択
  3. 必要に応じてAnkiConnect URLを設定（デフォルトは http://localhost:8765）
  4. Claude Desktopを再起動

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

Anthropic MCPディレクトリのレビューアー向け： 事前にデータが入ったサンプルデッキを使ったゼロから統合までのウォークスルーは、docs/reviewer-setup.mdにあります。

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

開発用途や高度な利用の場合（テストスイートの実行にはNode.js 24.9+が必要です — npm testスクリプトはESM専用のNestJS 12パッケージをrequire(esm)経由で読み込むため、Jestがサポートするのはそのバージョンのみです。サーバーを利用するための実行時要件は引き続き22.12.0+です）：

npm install
npm run build

AIクライアントへの接続

AIアシスタントがこのサーバーに到達する方法は、アシスタントがどこで実行されるかによって2つあります：

  • ローカル — サーバーがAIクライアント（Claude Desktop、Cursor、Cline、Zed、またはローカルブラウザセッション）と同じマシン上で実行されます。デスクトップMCPクライアントにはSTDIOを、ローカルWebベースのツールには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（ローカルWebベースAI）

HTTPモードは、MCP Streamable HTTPプロトコルを話すローカルWebサーバーとしてサーバーを実行します。これは、Webベースの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

ローカルHTTPサーバーをクラウドホスト型AIから到達可能にするには、以下のリモートオプションのいずれかを使用します。

リモート

ホスト型/リモート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に到達できるため、トンネルよりも安全性が低くなります。独自のngrokエンドポイントを管理する特別な理由がない限り、トンネルを優先してください。（グローバルなngrokインストールとauthtokenが必要です。）

--ngrokフラグは--host-header=rewriteでngrokを起動するため、ngrokは転送前にアップストリームのHostをlocalhostに書き換えます。これにより、ALLOWED_HOSTSにパブリックの*.ngrokドメインを追加しなくても、リクエストがループバック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でサーバーを設定するには、次のいずれかの方法を使用します：

  • 設定 → 開発者 → 設定の編集に移動
  • または設定ファイルを手動で編集

設定

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_URLAnkiConnect URLhttp://localhost:8765
ANKI_CONNECT_API_VERSIONAPIバージョン6
ANKI_CONNECT_API_KEYAnkiConnectで設定されている場合のAPIキー-
ANKI_CONNECT_TIMEOUTリクエストタイムアウト（ms）5000
READ_ONLY読み取り専用モードを有効にする（trueまたは1）false
PORTHTTPモード：リッスンするポート（--portフラグが優先）3000
HOSTHTTPモード：バインドするアドレス（--hostフラグが優先）127.0.0.1
ALLOWED_HOSTSHTTPモード：ループバック以外に受け入れる追加のHostヘッダー値（カンマ区切りのホスト名）。LAN/パブリックアドレスにバインドする場合やリバースプロキシの背後で実行する場合に必要です。HTTPモード設定を参照してください。ループバックのみ
ALLOWED_ORIGINSHTTPモード：ブラウザの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_HOSTSURLインポート用に特定のプライベートネットワークホストを許可（カンマ区切り、例：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自体は modelStyling から取得されます
  • updateNoteFields ツールはフィールド内のHTMLコンテンツをサポートし、CSSスタイルを保持します
  • 各ノートモデルには独自のCSSスタイルがあります。モデル固有のCSSを取得するには modelStyling を使用してください

更新時の警告

⚠️ 重要: 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）、ループバック（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 はブラウザで禁止されているヘッダーであるため、悪意のあるWebページはこれを偽造できません。これにより、リバウンドされたページが偽造された Host と Origin なしでローカルサーバーに到達し、MCPツールに到達するDNSリバインディング経路が閉じられます。許可されていない 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の間で直接行われます。これはこのサーバーの範囲外です。
  • 保持: 該当なし — サーバー側でデータは保持されません。
  • 連絡先: 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などのバージョンマネージャーを使用できます。

開発

トランスポートモード

このサーバーは、別々のエントリポイントを介して3つのMCPトランスポートモードをサポートしています：

STDIOモード（デフォルト）

  • Claude DesktopなどのローカルMCPクライアント用
  • 通信に標準入出力を使用
  • エントリポイント: dist/main-stdio.js
  • 実行: npm run start:prod:stdio または node dist/main-stdio.js
  • MCPBバンドル: STDIOモードを使用

HTTPモード（ストリーミングHTTP）

  • リモートMCPクライアントおよびWebベースの統合用
  • 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トンネルサービスを介したWebベースの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 - バインドアドレス（デフォルト：127.0.0.1（localhostのみ））
  • 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）

セキュリティ：

  • ホストヘッダー検証（DNSリバインディング保護） — すべてのHTTPリクエストは、許可リストに一致する Host ヘッダーを保持する必要があります。デフォルトでは、ポートに関係なくループバックホスト（localhost、127.0.0.1、::1）のみが受け入れられます。Host はブラウザで禁止されているヘッダーであるため、悪意のあるWebページはこれを偽造できません。これにより、リバウンドされたページが偽造された Host と Origin なしでサーバーに到達するDNSリバインディング経路が閉じられます。許可されていない Host は 403 で拒否されます。
  • オリジンヘッダー検証 — 存在するが許可されていない Origin/Referer を持つブラウザリクエストは拒否されます。Origin のないリクエスト（curl、Postman、MCP-over-HTTPクライアント）は許可されます。ホスト検証がリバインディングに対する防御です。
  • デフォルトで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

0.0.0.0/:: に ALLOWED_HOSTS なしでバインドすると、サーバーはループバックの 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/ - devDependenciesは mcpb clean によって削除されます）
  • パッケージメタデータ（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でのデバッグ

Claude Desktop内で実行中のMCPサーバーも、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"
      }
    }
  }
}

主な変更点: 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"]
    }
  ]
}
  1. デバッグパネルを開きます（Ctrl+Shift+D / Cmd+Shift+D）
  2. Attach to Anki MCP (Claude Desktop) を選択します
  3. 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未満の開発アプローチを採用しています:

  • 0.x.x - ベータ/開発バージョン（現在のフェーズ）

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

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

    • APIが安定しテストされたときにリリースされます
    • 破壊的変更にはメジャーバージョンの引き上げが必要です（2.0.0など）

現在のステータス: 0.27.0 - アクティブなベータ開発中。最近の機能には、コレクション全体のレビュー分析（review_stats は deck が省略されたときにすべてのデッキを集計）、モデルフィールド管理（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統合を構築するための強固な基盤が必要な場合、または機能を大幅に拡張する予定がある場合、このプロジェクトのアーキテクチャアプローチにより、長期的な保守とスケーリングが容易になります。

便利なリンク

ライセンスと帰属

このプロジェクトはMITライセンスの下でライセンスされています — 全文はLICENSEを参照してください。

Copyright © 2026 Anatoly Tarnavsky.

サードパーティの帰属

  • Anki® はAnkitects Pty Ltdの登録商標です。このプロジェクトは非公式のサードパーティツールであり、Ankitects Pty Ltdとは提携、承認、または後援されていません。Ankiロゴは、https://apps.ankiweb.net へのリンク付きでAnkiを参照するための代替ライセンスの下で使用されています。公式のAnkiアプリケーションについては、https://apps.ankiweb.net を訪問してください。

  • Model Context Protocol (MCP) はAnthropicによるオープンスタンダードです。MCPロゴは公式のMCPドキュメントリポジトリからのもので、MITライセンスの下で使用されています。MCPの詳細については、https://modelcontextprotocol.io を訪問してください。

  • これはAnkiとMCPテクノロジーを橋渡しする独立したプロジェクトです。すべての商標、サービスマーク、商号、製品名、およびロゴは、それぞれの所有者の財産です。