Anki MCP
公式AIアシスタントが間隔反復フラッシュカードアプリケーションAnkiと対話できるようにするMCPサーバー。
Anki MCPで何ができますか?
- Review due cards interactively — アシスタントに
get_due_cardsで復習予定のカードを取得させ、present_cardで表示し、rate_cardで評価を記録してもらいます。 - Create and style custom note types —
createModel、updateModelStyling、updateModelTemplatesを使用して、特定のフィールド、カードテンプレート、CSS を備えた新しいノートタイプを作成します。 - Batch-add flashcards from a list — ノートのセットを用意し、アシスタントに
addNotesでそれらをすべて一度に作成させ、同じデッキとモデルを共有させます。 - Search and update existing notes —
findNotesでデッキ、タグ、または復習ステータスでノートを検索し、updateNoteFields、addTags、またはremoveTagsを使用してフィールドやタグを変更します。 - Manage media in your collection —
storeMediaFileでローカルファイルパスから画像や音声をアップロードし、getMediaFilesNamesで保存済みファイルを一覧表示するか、未使用のメディアを削除します。 - Open Anki's GUI for manual editing —
guiBrowseでカードブラウザを開き、guiAddCardsでカード追加ダイアログを事前入力するか、guiEditNoteで特定のノートを編集します。
ドキュメント
Anki MCP Server
モデルコンテキストプロトコルを通じて、AnkiとAIアシスタントをシームレスに統合します
ベータ版 - このプロジェクトは活発に開発中です。APIや機能は変更される可能性があります。
AIアシスタントが間隔反復フラッシュカードアプリケーションであるAnkiと対話できるようにするモデルコンテキストプロトコル(MCP)サーバーです。
自然言語による対話でAnki体験を変革しましょう。まるで個人教師がいるかのようです。AIアシスタントは単に質問と回答を提示するだけでなく、概念を説明し、学習プロセスをより魅力的で人間らしくし、文脈を提供し、あなたの学習スタイルに適応します。その場でノートを作成・編集し、学習セッションを動的な会話に変えることができます。さらなる機能も近日登場予定です!
例とチュートリアル
このMCPサーバーをClaude Desktopで使用するための包括的なガイド、実例、ステップバイステップのチュートリアルについては、以下をご覧ください:
ankimcp.ai - 実践的な例とユースケースを含む完全なドキュメント
レビューアーセットアップガイドやサンプルAnkiデッキを含む補足ドキュメントについては、docs/を参照してください。
使用例
このサーバーが可能にするツールフローを示す3つの代表的なプロンプト:
-
「スペイン語デッキの復習を手伝って」 — アシスタントはAnkiWebと同期し(
sync)、期限の来たカードを取得し(デッキフィルター付きget_due_cards)、各カードを提示し(present_card)、あなたの評価を記録します(rate_card)。あなたに合わせた説明付きの自然な学習会話。 -
「RTLスタイルのアラビア語単語カードを10枚作成して」 — アシスタントはノートタイプを一覧表示し(
modelNames)、必要に応じてカスタムRTLモデルを作成し(createModel+ 右から左へのCSS用updateModelStyling)、カードを一括作成します(addNotes)。 -
「この画像をダウンロードフォルダから選択中のノートの表面にインポートして」 — アシスタントはローカルファイルをアップロードし(ファイルパス付き
storeMediaFile)、ブラウザで現在選択されているノートを読み取り(guiSelectedNotes+notesInfo)、表面フィールドを<img>タグで更新します(updateNoteFields)。
利用可能なツール
サーバーは42のMCPツールを公開しています — 日常的なAnki操作のための31の必須ツールと、ノート編集/作成ワークフローのためにAnkiデスクトップインターフェースを操作する11のGUIツールです。
必須ツール
復習と学習
sync- AnkiWebと同期し、最新データを取得して変更をプッシュしますget_due_cards- 復習期限の来たカードを取得します(オプションでデッキでフィルタリング)get_cards- 状態(期限付き、新規、学習中、一時停止、非表示)とデッキで柔軟にフィルタリングしてカードを取得しますpresent_card- 質問/表面を表示して復習用のカードを表示しますrate_card- カードのパフォーマンスを評価し(再学習、難しい、良い、簡単)、次の復習をスケジュールします
注記: カード
front/backの内容は、Ankiが表示するように、独自のテンプレートからカードごとにレンダリングされるため、反転カードや穴埋めカードは正しい方向で表示されます。カードテンプレートによって追加された静的なテキストも出力に表示されます。
デッキ管理
listDecks- すべてのデッキを一覧表示します(オプションでデッキごとのカード数統計付き)deckStats- 単一デッキの包括的な統計情報を取得します(カウント、容易さ/間隔の分布)createDeck- 新しい空のデッキを作成します(Parent::Childをサポート、最大2レベル)changeDeck- カードを別のデッキに移動します(存在しない場合は作成されます)
ノート管理
addNote- 指定されたフィールドとタグで単一のノートを作成しますaddNotes- デッキとモデルを共有する最大100枚のノートを一括作成します(部分的な成功をサポート)findNotes- Ankiクエリ構文(deck:、tag:、is:dueなど)を使用してノートを検索しますnotesInfo- ノートに関する詳細情報を取得します(フィールド、タグ、CSSスタイリング)updateNoteFields- 既存のノートフィールドを更新します(CSS対応、HTMLコンテンツをサポート)deleteNotes- ノートと関連するすべてのカードを削除します(破壊的、確認が必要)
タグ管理
getTags- コレクション内のすべてのタグを取得します(重複を避けるために最初に使用)addTags- 指定されたノートにスペース区切りのタグを追加しますremoveTags- 指定されたノートからスペース区切りのタグを削除しますreplaceTags- 指定されたノート全体でタグの名前を変更しますclearUnusedTags- どのノートにも使用されていない孤立したタグを削除します(破壊的)
メディア管理
getMediaFilesNames-collection.media内のメディアファイルを一覧表示します(オプションでパターンでフィルタリング)retrieveMediaFile- メディアファイルをbase64コンテンツとしてダウンロードしますstoreMediaFile- base64データ、絶対ファイルパス、またはURLからメディアをアップロードしますdeleteMediaFile-collection.mediaからメディアファイルを削除します(破壊的)
💡 画像のベストプラクティス:
- ✅ ファイルパスを使用(例:
/Users/you/image.png) - 高速で効率的 - ✅ URLを使用(例:
https://example.com/image.jpg) - 直接ダウンロード - ❌ base64を避ける - 非常に遅く、トークン効率が悪い
画像の場所をClaudeに伝えるだけで、最も効率的な方法を使用して自動的にアップロードを処理します。
モデル/テンプレート管理
modelNames- 利用可能なすべてのノートタイプ/モデルを一覧表示しますmodelFieldNames- 特定のノートタイプのフィールド名を取得しますmodelStyling- ノートタイプのCSSスタイリング情報を取得しますmodelTemplates- ノートタイプのカードテンプレート(表面と裏面のHTML)を取得しますcreateModel- カスタムフィールド、カードテンプレート、CSSで新しいノートタイプを作成します(例:RTLモデル)updateModelStyling- 既存のノートタイプのCSSスタイリングを更新します(そのすべてのカードに適用されます)updateModelTemplates- 既存のノートタイプのカードテンプレート(表面と裏面のHTML)を更新します(そのすべてのカードに適用されます)addModelField- 既存のノートタイプに新しいフィールドを追加します(末尾に追加、または特定の位置に挿入)removeModelField- 既存のノートタイプからフィールドを削除します(すべてのノートからその内容を削除します。明示的な確認が必要です)renameModelField- 既存のノートタイプのフィールド名を変更します(古い名前を参照しているカードテンプレートは別途更新する必要があります)repositionModelField- 既存のノートタイプ内のフィールドの位置を変更します
統計
collection_stats- デッキごとの内訳を含む、すべてのデッキにわたる集計統計review_stats- 復習履歴分析(時間的パターン、保持率指標、学習ストリーク)
GUIツール
Ankiデスクトップインターフェースを操作するツール。ノート編集/作成およびデッキ管理ワークフローを目的としており、復習セッション用ではありません。
guiBrowse- カードブラウザを開き、カードを検索しますguiSelectCard- カードブラウザで特定のカードを選択しますguiSelectedNotes- カードブラウザで現在選択されているノートのIDを取得しますguiAddCards- 事前設定されたノート詳細でカード追加ダイアログを開きますguiEditNote- 特定のノートのノートエディタを開きますguiDeckOverview- 特定のデッキのデッキ概要ダイアログを開きますguiDeckBrowser- デッキブラウザダイアログを開きますguiCurrentCard- 復習モードの現在のカードに関する情報を取得しますguiShowQuestion- 現在のカードの質問面を表示しますguiShowAnswer- 現在のカードの回答面を表示しますguiUndo- Ankiでの最後の操作を元に戻します
前提条件
- AnkiConnectプラグインがインストールされたAnki
- 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に推奨)
このMCPサーバーをClaude Desktop用にインストールする最も簡単な方法:
- リリースページから最新の
.mcpbバンドルをダウンロードします - Claude Desktopで、拡張機能をインストールします:
- 方法1: 設定 → 拡張機能に移動し、
.mcpbファイルをドラッグアンドドロップします - 方法2: 設定 → 開発者 → 拡張機能 → 拡張機能のインストールに移動し、
.mcpbファイルを選択します
- 方法1: 設定 → 拡張機能に移動し、
- 必要に応じてAnkiConnectのURLを設定します(デフォルトは
http://localhost:8765) - Claude Desktopを再起動します
以上です!バンドルにはサーバーをローカルで実行するために必要なものがすべて含まれています。
Anthropic MCPディレクトリレビューア向け: 事前入力されたサンプルデッキを使用したゼロからの統合ウォークスルーは、
docs/reviewer-setup.mdにあります。
ソースからインストール(開発用)
開発または高度な使用法向け:
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など)の標準トランスポートです。クライアントはサーバーをサブプロセスとして起動し、標準入出力を介して通信します。
サポートされているクライアント:
- Claude Desktop
- Cursor IDE - AI搭載コードエディタ
- Cline - AI支援用VS Code拡張機能
- Zed Editor - 高速でモダンなコードエディタ
- 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"
}
}
}
}
設定ファイルの場所:
- Cursor IDE:
~/.cursor/mcp.json(macOS/Linux)または%USERPROFILE%\.cursor\mcp.json(Windows) - Cline: VS Codeの設定UIからアクセス可能
- Zed Editor: 拡張機能マーケットプレイスを通じてMCP拡張機能としてインストール
クライアント固有の機能とトラブルシューティングについては、MCPクライアントのドキュメントを参照してください。ビルドされたdist/main-stdio.jsを直接指す設定については、Claude Desktopへの接続も参照してください。
HTTP(ローカルWebベースAI)
HTTPモードは、MCPストリーミング可能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 Device Authorization Grantを使用します。ログインすると、コードが既に埋め込まれた承認ページがブラウザで自動的に開きます。入力するものはなく、承認するだけです。(ブラウザを開けない場合、フォールバックとして、ターミナルに確認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) を別のホストに向けると、認証もそのホストに移動します。
仕組み: トンネルモードは、MCPサーバーをインメモリトランスポートの背後でインプロセス実行します (McpModuleは組み込みトランスポートなしで開始されます)。TunnelMcpServiceはそのインメモリトランスポートをMCPサーバーに接続し、TunnelClientはWebSocket経由でリモートトンネルサービスにブリッジし、MCPリクエストを中継してレスポンスを返します。AnkiConnectは依然としてローカルマシン上でのみアクセスされます。
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に書き換えます。これにより、パブリック*.ngrokドメインをALLOWED_HOSTSに追加しなくても、リクエストはループバックホスト許可リスト内に保持されます (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 <port> Port to listen on (HTTP mode, default: 3000)
-h, --host <host> Host to bind to (HTTP mode, default: 127.0.0.1)
-a, --anki-connect <url> AnkiConnect URL (default: http://localhost:8765)
--ngrok Start ngrok tunnel (requires global ngrok installation)
--read-only Run in read-only mode (blocks all write operations)
--help Show help message
Usage with npx (no installation needed):
npx @ankimcp/anki-mcp-server # HTTP mode
npx @ankimcp/anki-mcp-server --port 8080 # Custom port
npx @ankimcp/anki-mcp-server --stdio # STDIO mode
npx @ankimcp/anki-mcp-server --tunnel # Managed tunnel mode
npx @ankimcp/anki-mcp-server --ngrok # HTTP mode with ngrok tunnel
npx @ankimcp/anki-mcp-server --read-only # Read-only mode
Usage with global installation:
npm install -g @ankimcp/anki-mcp-server # Install once
ankimcp # HTTP mode
ankimcp --port 8080 # Custom port
ankimcp --stdio # STDIO mode
ankimcp --tunnel # Managed tunnel mode
ankimcp --ngrok # HTTP mode with ngrok tunnel
ankimcp --read-only # Read-only mode
読み取り専用モード (全モード)
--read-onlyフラグは、Ankiコレクションへの変更を防ぎます。有効にすると:
- すべての読み取り操作は正常に機能します (デッキの閲覧、カードの表示、ノートの検索)
- 復習操作は許可されます (同期、answerCards、一時停止/一時停止解除)
- コンテンツの変更はブロックされます (addNote、deleteNotes、createDeck、updateNoteFieldsなど)
- 誤って変更するリスクなしにAnkiデータを安全に探索するのに役立ちます
# HTTP mode with read-only
ankimcp --read-only
# STDIO mode with read-only
ankimcp --stdio --read-only
# Can combine with other flags
ankimcp --ngrok --read-only
環境変数で読み取り専用モードを有効にすることもできます:
READ_ONLY=true ankimcp
またはMCPクライアント設定で:
{
"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_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 |
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"- 動詞タグを持つスペイン語デッキのノート (AND)"deck:Spanish OR deck:French"- いずれかのデッキのノート
重要な注意点
CSSとHTMLの処理
notesInfoツールは、適切なレンダリング認識のためにCSSスタイリング情報を返しますupdateNoteFieldsツールは、フィールド内のHTMLコンテンツをサポートし、CSSスタイリングを保持します- 各ノートモデルには独自のCSSスタイリングがあります -
modelStylingを使用してモデル固有のCSSを取得します
更新に関する警告
⚠️ 重要: updateNoteFieldsを使用する場合、更新中にAnkiのブラウザでノートを表示しないでください。表示すると、フィールドが正しく更新されません。更新前にブラウザを閉じるか、別のノートに切り替えてください。詳細については、既知の問題を参照してください。
削除の安全性
deleteNotesツールは、誤った削除を防ぐために明示的な確認 (confirmDeletion: true) を必要とします。ノートを削除すると、関連するすべてのカードが完全に削除されます。
セキュリティ
メディアファイルのパスとURLの検証
メディアツール (storeMediaFile, retrieveMediaFile, deleteMediaFile) とupdateNoteFieldsオーディオ/画像フィールドには、プロンプトインジェクションによる悪用を防ぐためのセキュリティ検証が含まれています:
- ファイルパスインポートは、メディアファイルタイプ (画像、音声、動画) のみに制限されています。非メディアファイル (SSHキー、資格情報、シェル設定など) は、MIMEタイプに基づいて拒否されます。追加のファイルタイプを許可するには
MEDIA_ALLOWED_TYPESを設定し、インポートを特定のディレクトリに制限するにはMEDIA_IMPORT_DIRを設定します。 - URLインポートは、SSRF攻撃に対して検証されます。プライベートネットワーク (10.x、172.16.x、192.168.x)、ループバック (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モード設定を参照してください。
avishaigo-commitsおよびyotampe-plutoによって報告されたDNSリバインディングの脆弱性。
プライバシーポリシー
この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 ストリーミング可能 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 サーバーはインメモリトランスポートの背後でプロセス内実行されます。
TunnelMcpServiceがそれを MCP サーバーに接続し、TunnelClientが WebSocket 経由でトンネルサービスにブリッジします。 - エントリポイント:
dist/main-tunnel.js - 実行:
node dist/main-tunnel.js --tunnel(またはankimcp --tunnel) - 認証:
ankimcp --login/ankimcp --logout; 認証情報は~/.ankimcp/credentials.json(0600) に保存されます - 開発:
npm run start:dev:tunnel(監視モード、--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
このコマンドは以下を実行します:
package.jsonからmanifest.jsonにバージョンを同期- 古い
.mcpbファイルを削除 - TypeScript プロジェクトをビルド
dist/とnode_modules/を.mcpbファイルにパッケージ化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 モード (ストリーミング可能な HTTP) をテストする場合は、「接続タイプ: プロキシ経由」を使用して CORS エラーを回避してください。
ステップ 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
- 実行 → 設定の編集 に移動します
- 新しい Node.js/Chrome に接続 設定を追加します
- ポートを
9229に設定します - デバッグ をクリックして接続します
VS Code
- デバッグパネルを開きます (Ctrl+Shift+D / Cmd+Shift+D)
- MCP サーバーのデバッグ (接続) 設定を選択します
- 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
- 実行 → 設定の編集 に移動します
- + ボタンをクリックし、Node.js/Chrome に接続 を選択します
- 設定:
- 名前:
Attach to Anki MCP (Claude Desktop) - ホスト:
localhost - ポート:
9229 - 接続先:
Node.js < 8またはChrome or Node.js > 6.3(WebStorm のバージョンによって異なります)
- 名前:
- OK をクリックします
- デバッグ (Shift+F9) をクリックして接続します
VS Code
.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"]
}
]
}
- デバッグパネルを開きます (Ctrl+Shift+D / Cmd+Shift+D)
- Anki MCP に接続 (Claude Desktop) を選択します
- 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.22.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ロゴは、https://apps.ankiweb.net へのリンクと共にAnkiを参照するための代替ライセンスの下で使用されています。公式のAnkiアプリケーションについては、https://apps.ankiweb.net をご覧ください。
-
Model Context Protocol (MCP) はAnthropicによるオープンスタンダードです。MCPロゴは公式のMCPドキュメントリポジトリからのものであり、MITライセンスの下で使用されています。MCPの詳細については、https://modelcontextprotocol.io をご覧ください。
-
これはAnkiとMCP技術を橋渡しする独立したプロジェクトです。すべての商標、サービスマーク、トレードネーム、製品名、ロゴは、それぞれの所有者の財産です。