🚀 Anki MCP Server
このプロジェクトは、Model Context Protocol (MCP) を介して、AIアシスタントとアンキ(Anki)の間のシームレスな統合を可能にするサーバです。自然言語対話により、アンキの学習体験を変革し、プライベートチューターのような学習環境を提供します。
⚠️ 重要なお知らせ
このプロジェクトは名前が変更され、移動されました(v0.8.2以降):
- パッケージ:
anki-mcp-http → @ankimcp/anki-mcp-server
- コマンド:
anki-mcp-http → ankimcp または anki-mcp-server
- リポジトリ:
anki-mcp/anki-mcp-desktop → ankimcp/anki-mcp-server
古い anki-mcp-http パッケージは下位互換性のために引き続き公開されますが、非推奨となりました。新しいパッケージに移行してください。
この変更の詳細を読む →

ベータ版 - このプロジェクトは現在積極的に開発中です。APIや機能は変更される可能性があります。
🚀 クイックスタート
このMCPサーバを使用するには、以下の前提条件を満たす必要があります。
サーバは2つのモードで動作します。
- ローカルモード (STDIO) - コンピュータ上のClaude Desktop用(ほとんどのユーザに推奨)
- リモートモード (HTTP) - ChatGPTやClaude.aiなどのウェブベースのAIアシスタント用
オプション1: MCPBバンドル(推奨 - ローカルモード)
Claude Desktop用のMCPサーバをインストールする最も簡単な方法は、以下の手順です。
- リリース ページから最新の
.mcpb バンドルをダウンロードする
- Claude Desktopで拡張機能をインストールする
- 方法1: 設定 → 拡張機能に移動し、
.mcpb ファイルをドラッグアンドドロップする
- 方法2: 設定 → 開発者 → 拡張機能 → 拡張機能をインストールに移動し、
.mcpb ファイルを選択する
- 必要に応じてAnkiConnect URLを設定する(デフォルトは
http://localhost:8765)
- Claude Desktopを再起動する
オプション2: STDIO付きのNPMパッケージ(他のMCPクライアント用)
Cursor IDE、Cline、またはZed EditorなどのMCPクライアントでAnkiを使用する場合は、--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拡張機能としてインストール
オプション3: HTTPモード(リモートAIアシスタント用)
ブラウザでChatGPTやClaude.aiとAnkiを使用する場合は、このモードを使用します。このモードでは、ウェブベースのAIツールをローカルのAnkiに接続できます。
仕組み(簡単な説明):
- コンピュータ(Ankiがインストールされている場所)で小さなサーバを実行する
- 組み込みの
--ngrok フラグを使用して、自動的に公開トンネルURLを作成する
- そのURLをChatGPTやClaude.aiと共有する
- これでAIがインターネットを通じてAnkiと通信できるようになります!
v0.8.0の新機能: --ngrok フラグによるngrokサポートの統合 - ngrokを別々に実行する必要はありません!
セットアップ - 方法を選択:
方法1: npxを使用する(推奨 - インストール不要)
npx @ankimcp/anki-mcp-server
npx @ankimcp/anki-mcp-server --ngrok
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765
方法2: グローバルインストールを使用する
npm install -g @ankimcp/anki-mcp-server
ankimcp
ankimcp --ngrok
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
CLIオプション:
ankimcp [options]
Options:
--stdio STDIOモードで実行する(MCPクライアント用)
-p, --port <port> リッスンするポート(HTTPモード、デフォルト: 3000)
-h, --host <host> バインドするホスト(HTTPモード、デフォルト: 127.0.0.1)
-a, --anki-connect <url> AnkiConnect URL(デフォルト: http://localhost:8765)
--ngrok ngrokトンネルを開始する(グローバルなngrokインストールが必要)
--help ヘルプメッセージを表示する
npxを使用した使用法(インストール不要):
npx @ankimcp/anki-mcp-server
npx @ankimcp/anki-mcp-server --port 8080
npx @ankimcp/anki-mcp-server --stdio
npx @ankimcp/anki-mcp-server --ngrok
グローバルインストールを使用した使用法:
npm install -g @ankimcp/anki-mcp-server
ankimcp
ankimcp --port 8080
ankimcp --stdio
ankimcp --ngrok
ngrokを使用する場合:
方法1: 統合(推奨 - 1つのコマンド)
npm install -g ngrok
ngrok config add-authtoken <your-token>
ankimcp --ngrok
方法2: 手動(2つのターミナル)
ankimcp
ngrok http 3000
--ngrok フラグの利点:
- ✅ 2つのターミナルではなく1つのコマンドで済む
- ✅ Ctrl+Cを押すと自動的にクリーンアップされる
- ✅ 起動バナーに直接URLが表示される
- ✅ カスタムポートでも動作する:
ankimcp --port 8080 --ngrok
セキュリティに関する注意: ngrok URLを持っている人は誰でもAnkiにアクセスできるため、そのURLは秘密にしておいてください!
オプション4: ソースから手動インストールする(ローカルモード)
開発や高度な使用法のために、以下のコマンドを実行します。
npm install
npm run build
✨ 主な機能
- レビューと学習: アンキのカードを同期、レビュー、評価することができます。
- デッキ管理: デッキの一覧表示、新規作成が可能です。
- ノート管理: ノートの作成、検索、更新、削除ができます。
- メディア管理: オーディオや画像などのメディアファイルを管理できます。
- モデル/テンプレート管理: ノートタイプの一覧表示、フィールド情報の取得、CSSスタイリングの取得ができます。
📦 インストール
上記のクイックスタートセクションで説明した通り、サーバは異なるモードでインストールおよび設定することができます。
💻 使用例
基本的な使用法
findNotes(query: "deck:Spanish")
notesInfo(notes: [1234567890, 1234567891])
updateNoteFields(note: {
id: 1234567890,
fields: {
"Front": "<b>¿Cómo estás?</b>",
"Back": "How are you?"
}
})
deleteNotes(notes: [1234567890], confirmDeletion: true)
高度な使用法
📚 ドキュメント
例とチュートリアル
このMCPサーバをClaude Desktopと共に使用するための包括的なガイド、実際の例、およびステップバイステップのチュートリアルについては、次のサイトを参照してください。
ankimcp.ai - 実用的な例とユースケースを含む完全なドキュメント
利用可能なツール
レビューと学習
sync - AnkiWebと同期する
get_due_cards - 復習用のカードを取得する
present_card - 復習用のカードを表示する
rate_card - カードの性能を評価する
デッキ管理
list_decks - 利用可能なデッキを表示する
createDeck - 新しいデッキを作成する
ノート管理
addNote - 新しいノートを作成する
findNotes - Ankiクエリ構文を使用してノートを検索する
notesInfo - ノートの詳細情報(フィールド、タグ、CSS)を取得する
updateNoteFields - 既存のノートフィールドを更新する(CSS対応、HTMLをサポート)
deleteNotes - ノートとそれに関連するカードを削除する
メディア管理
mediaActions - メディアファイル(オーディオ/画像)を管理する
storeMediaFile - base64データ、ファイルパス、またはURLからメディアをアップロードする
retrieveMediaFile - メディアをbase64としてダウンロードする
getMediaFilesNames - オプションのパターンフィルタリングでメディアファイルを一覧表示する
deleteMediaFile - メディアファイルを削除する
💡 画像のベストプラクティス:
- ✅ ファイルパスを使用する(例:
/Users/you/image.png) - 高速かつ効率的
- ✅ URLを使用する(例:
https://example.com/image.jpg) - 直接ダウンロード
- ❌ base64を避ける - 非常に遅く、トークン効率が悪い
モデル/テンプレート管理
modelNames - ノートタイプを一覧表示する
modelFieldNames - ノートタイプのフィールドを取得する
modelStyling - ノートタイプのCSSスタイリングを取得する
環境変数(オプション)
| 属性 |
詳情 |
ANKI_CONNECT_URL |
AnkiConnectのURL。デフォルトは http://localhost:8765 です。 |
ANKI_CONNECT_API_VERSION |
APIのバージョン。デフォルトは 6 です。 |
ANKI_CONNECT_API_KEY |
AnkiConnectで設定されたAPIキー。 |
ANKI_CONNECT_TIMEOUT |
リクエストのタイムアウト時間(ミリ秒)。デフォルトは 5000 です。 |
重要な注意事項
CSSとHTMLの扱い
notesInfo ツールは、適切なレンダリングのためにCSSスタイリング情報を返します。
updateNoteFields ツールは、フィールド内のHTMLコンテンツをサポートし、CSSスタイリングを保持します。
- 各ノートモデルには独自のCSSスタイリングがあります -
modelStyling を使用してモデル固有のCSSを取得します。
更新の警告
⚠️ 重要: updateNoteFields を使用する際に、更新中にAnkiのブラウザでノートを表示しないでください。そうしないと、フィールドが適切に更新されません。更新する前にブラウザを閉じるか、別のノートに切り替えてください。詳細については、既知の問題 を参照してください。
削除の安全性
deleteNotes ツールは、誤削除を防止するために明示的な確認(confirmDeletion: true)を必要とします。ノートを削除すると、関連するすべてのカードが永久に削除されます。
🔧 技術詳細
トランスポートモード
このサーバは、2つのMCPトランスポートモードをサポートしています。
- STDIOモード(デフォルト): ローカルのMCPクライアント(Claude Desktopなど)用。標準入出力を使用して通信します。
- HTTPモード(Streamable HTTP): リモートのMCPクライアントやウェブベースの統合に使用します。MCP Streamable HTTPプロトコルを使用します。
ビルドコマンド
npm run build
npm run start:dev:stdio
npm run start:dev:http
npm run type-check
npm run lint
npm run mcpb:bundle
NPMパッケージのテスト(ローカル)
npmパッケージを公開する前に、ローカルでテストすることができます。
npm run pack:local
npm run install:local
ankimcp
npm run uninstall:local
テストコマンド
npm test
npm run test:unit
npm run test:tools
npm run test:workflows
npm run test:e2e
npm run test:cov
npm run test:watch
npm run test:debug
npm run test:ci
テストカバレッジ
このプロジェクトは、以下の項目について最低70%のカバレッジ閾値を維持しています。
カバレッジレポートは coverage/ ディレクトリに生成されます。
既知の問題
既知の問題と制限事項の包括的なリストについては、以下のドキュメントを参照してください。
既知の問題のドキュメント
重大な制限事項
ブラウザで表示中のノートの更新が失敗する
⚠️ 重要: updateNoteFields を使用してノートを更新する際に、Ankiのブラウザウィンドウでノートが現在表示されている場合、更新は無声に失敗します。これは上位のAnkiConnectの制限事項です。
回避策: 更新する前に、常にブラウザを閉じるか、別のノートに移動してください。
詳細やその他の既知の問題については、完全なドキュメント を参照してください。
開発
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 という名前になり、ワンクリックインストール用に配布することができます。
Claude Desktopでのログ記録
Claude DesktopでMCPB拡張機能として実行する場合、ログは以下の場所に書き込まれます。
ログの場所: ~/Library/Logs/Claude/ (macOS)
ログは複数のファイルに分割されています。
- main.log - 一般的なClaude Desktopアプリケーションログ
- mcp-server-Anki MCP Server.log - この拡張機能のMCPプロトコルメッセージ
- mcp.log - すべてのサーバからの統合MCPログ
MCPサーバのデバッグ
MCPサーバは、MCPインスペクターを使用して、IDE(WebStorm、VS Codeなど)からデバッガをアタッチすることでデバッグすることができます。
Claude Desktopでのデバッグ
Claude Desktop内でMCPサーバを実行している間に、Node.jsデバッガを有効にしてIDEをアタッチすることで、デバッグすることもできます。
バージョニング
このプロジェクトは、Semantic Versioning に従い、1.0より前の開発アプローチを採用しています。
- 0.x.x - ベータ/開発バージョン(現在のフェーズ)
- 0.1.x - バグ修正とパッチ
- 0.2.0+ - 新機能または小幅な改善
- 0.xバージョンでは破壊的な変更が許容されます
- 1.0.0 - 最初の安定リリース
- APIが安定し、テストされたときにリリースされます
- 破壊的な変更にはメジャーバージョンのアップデート(2.0.0など)が必要です
現在の状態: 0.8.0 - アクティブなベータ開発中。新機能には、統合されたngrokトンネリング(--ngrok フラグ)、証拠に基づくフラッシュカード作成用の twenty_rules プロンプト、メディアファイル管理、および改善されたプロンプトシステムが含まれます。APIはフィードバックとテストに基づいて変更される可能性があります。
似たプロジェクト
Anki MCP統合を探索している場合は、この分野の他のプロジェクトを紹介します。
- ステータス: 放棄されたように見えます(最近の更新がありません)
- Anki MCP統合の初期実装
- アプローチ: 軽量な単一ファイル実装
- アーキテクチャ: すべてのツールが1つのファイルにある手続き型コード構造
- 適した用途: 単純なユースケース、最小限の依存関係
このプロジェクトが異なる理由:
- エンタープライズグレードのアーキテクチャ: 依存性注入を備えたNestJSに基づいて構築されています。
- モジュール化された設計: 各ツールは明確な関心の分離を持つ別々のクラスです。
- 保守性: 既存のコードに触れることなく新機能を簡単に拡張できます。
- テスト: 70%のカバレッジ要件を持つ包括的なテストスイート。
- 型安全性: Zod検証を備えた厳格なTypeScript。
- エラーハンドリング: ユーザーに役立つフィードバックを伴う堅牢なエラーハンドリング。
- 本番環境対応: 適切なロギング、進捗報告、およびMCPBバンドルサポート。
- 拡張性: 基本的なツールから複雑なワークフローまで簡単に拡張できます。
使用例: 高度なAnki統合を構築するための堅牢な基盤が必要な場合、または機能を大幅に拡張する予定がある場合は、このプロジェクトのアーキテクチャアプローチが長期的に保守と拡張を容易にします。
便利なリンク
📄 ライセンス
このプロジェクトは、GNU Affero General Public License v3.0以降(AGPL-3.0-or-later)の下でライセンスされています。
なぜAGPL-3.0なのか?
このライセンスは、将来的な統合シナリオでAnkiのAGPL-3.0ライセンスとの互換性を維持するために選択されました。
これが意味すること:
- 個人使用: ソフトウェアを自由に使用できます。
- 他の人のためにサービスとして実行する: ソースコードへのアクセスを提供する必要があります(AGPLセクション13)。
- 変更して配布する: 改良点をAGPL-3.0-or-laterの下で共有する必要があります。
完全なライセンス条項については、LICENSE ファイルを参照してください。
サードパーティの帰属
- 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技術を橋渡しする独立したプロジェクトです。すべての商標、サービスマーク、商号、製品名、およびロゴは、それぞれの所有者の財産です。