AnkiMCP Server (アドオン)

Model Context Protocol (MCP) を介して、AnkiのコレクションをAIアシスタントに公開するAnkiアドオンです。

これは何ですか？

AnkiMCP Serverは、Anki内でローカルMCPサーバーを実行し、ClaudeのようなAIアシスタントがあなたのフラッシュカードコレクションと対話できるようにします。これにより、AIを活用した学習セッション、カード作成、コレクション管理が可能になります。

ankimcp.ai プロジェクトの一部です。

Related MCP server: Anki MCP Server

初回実行時の注意点

初回実行時、このアドオンはPyPIから pydantic_core (~2MB) をダウンロードします。これは、pydantic_core にプラットフォーム固有のバイナリ（Windows/macOS/Linux）が含まれており、単一のアドオンファイルにバンドルできないためです。

機能

• ローカルHTTPサーバー - デフォルトで http://127.0.0.1:3141/ で動作

• MCPプロトコル - あらゆるMCPクライアント（Claude Desktopなど）と互換性あり

• 自動起動 - Anki起動時にサーバーが自動的に開始

• トンネル対応 - Cloudflare Tunnel、ngrokなどで動作可能

• クロスプラットフォーム - macOS、Windows、Linux (x64およびARM) で動作

インストール

AnkiWebから (推奨)

1. Ankiを開き、ツール → アドオン → アドオンを取得... に移動します。

2. コードを入力: 124672614

3. Ankiを再起動します。

GitHub Releasesから

1. Releases から anki_mcp_server.ankiaddon をダウンロードします。

2. ダブルクリックしてインストールするか、ツール → アドオン → ファイルからインストール... を使用します。

3. Ankiを再起動します。

NixOS

flakesを使用する場合 (推奨)

flake入力を追加し、ビルド済みのパッケージを使用します：

# flake.nix
{
  inputs.anki-mcp.url = "github:ankimcp/anki-mcp-server-addon";

  outputs = { nixpkgs, anki-mcp, ... }: {
    # Option A: Standalone — Anki with the addon pre-installed
    environment.systemPackages = [
      anki-mcp.packages.${system}.default
    ];

    # Option B: Composable with other addons via overlay
    nixpkgs.overlays = [ anki-mcp.overlays.default ];
    environment.systemPackages = [
      (pkgs.anki.withAddons [ pkgs.ankiAddons.anki-mcp-server ])
    ];
  };
}

flakesを使用しない場合

# configuration.nix
{ pkgs, ... }:
let
  python3 = pkgs.python3;

  ankiMcpPythonDeps = python3.withPackages (ps: with ps; [
    mcp pydantic pydantic-settings starlette uvicorn anyio httpx websockets
  ]);

  anki-mcp-server = pkgs.anki-utils.buildAnkiAddon (finalAttrs: {
    pname = "anki-mcp-server";
    version = "0.13.0";
    src = pkgs.fetchFromGitHub {
      owner = "ankimcp";
      repo = "anki-mcp-server-addon";
      rev = "v${finalAttrs.version}";
      hash = ""; # nix will tell you the correct hash on first build
    };
    sourceRoot = "${finalAttrs.src.name}/anki_mcp_server";
  });

  ankiWithMcp = pkgs.anki.withAddons [ anki-mcp-server ];

  ankiWrapped = pkgs.symlinkJoin {
    name = "anki-with-mcp";
    paths = [ ankiWithMcp ];
    nativeBuildInputs = [ pkgs.makeWrapper ];
    postBuild = ''
      wrapProgram $out/bin/anki \
        --prefix PYTHONPATH ':' "${ankiMcpPythonDeps}/${python3.sitePackages}"
    '';
  };
in
{
  environment.systemPackages = [ ankiWrapped ];
}

使用方法

Ankiを開くとサーバーが自動的に開始されます。ステータスは ツール → AnkiMCP Server Settings... から確認できます。

Claude Desktopとの接続

Node.js のインストールが必要です。Claude Desktopの設定ファイル（macOSの場合は ~/Library/Application Support/Claude/claude_desktop_config.json）に追加します：

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:3141"]
    }
  }
}

注: Claude DesktopはJSON設定内でHTTPサーバーをネイティブサポートしていないため、mcp-remote がstdio経由で接続をブリッジします。

Claude Codeとの接続

claude mcp add anki --transport http http://127.0.0.1:3141/

設定

Ankiの ツール → アドオン → AnkiMCP Server → 設定 から編集します：

{
  "mode": "http",
  "http_port": 3141,
  "http_host": "127.0.0.1",
  "http_path": "",
  "cors_origins": [],
  "cors_expose_headers": ["mcp-session-id", "mcp-protocol-version"],
  "auto_connect_on_startup": true,
  "disabled_tools": [],
  "media_import_dir": "",
  "media_allowed_types": [],
  "media_allowed_hosts": []
}

ツールの無効化

特定のツールやアクションをAIクライアントから隠し、トークン消費量を削減します：

{
  "disabled_tools": [
    "sync",
    "card_management:bury",
    "card_management:unbury"
  ]
}

• "tool_name" — ツール全体を無効化

• "tool_name:action" — マルチアクションツール内の特定のアクションを無効化

無効化されたツールはMCPスキーマから完全に削除されるため、AIクライアントからは一切見えなくなります。ツール名やアクション名のタイプミスはコンソール警告を生成します。

カスタムパス

http_path を設定すると、MCPエンドポイントをカスタムパス配下で提供できます。トンネル（Cloudflare、ngrok）経由でAnkiを公開する際、完全にオープンなエンドポイントを避けるのに便利です：

{
  "http_path": "my-secret-path"
}

サーバーはルートではなく http://localhost:3141/my-secret-path/ でアクセス可能になります。デフォルトの動作にする場合は空のままにしてください。

CORS設定

ブラウザベースのMCPクライアント（Webホスト型のMCP Inspectorなど）を許可するには、許可されたオリジンを追加します：

{
  "cors_origins": ["https://inspector.example.com", "http://localhost:5173"]
}

すべてのオリジンを許可するには ["*"] を使用します（本番環境では推奨されません）。

cors_expose_headers 設定は、ブラウザが読み取れるレスポンスヘッダーを制御します。デフォルト値（mcp-session-id、mcp-protocol-version）は、MCP Streamable HTTPプロトコルをブラウザで動作させるために必要です。

メディアセキュリティ

メディアパス・トラバーサル脆弱性を責任を持って開示してくださった 高橋秀明 氏（コロンビア大学）に感謝いたします。

store_media_file ツールは、パス・トラバーサル攻撃やSSRF攻撃を防ぐためにすべての入力を検証します：

• ファイルパス は、MIMEタイプチェックによりメディアファイル（画像、音声、動画）のみに制限されます

• URL は http:// または https:// を使用する必要があり、プライベート/内部ネットワークをターゲットにすることはできません

• ファイル名 は、パス・トラバーサルシーケンスを除去するためにサニタイズされます

設定によるオプションの強化：

{
  "media_import_dir": "/Users/me/anki-media",
  "media_allowed_types": ["application/pdf"],
  "media_allowed_hosts": ["192.168.1.50", "my-nas.local"]
}

• media_import_dir — ファイルパスのインポートをこのディレクトリツリー内に制限します（空の場合は制限なし）

• media_allowed_types — 画像/音声/動画以外のMIMEタイプを許可します

• media_allowed_hosts — プライベートネットワークブロックをバイパスする特定のホストを許可します

利用可能なツール

基本ツール

FSRSツール

GUIツール

これらのツールはAnkiのユーザーインターフェースと対話します：

リソース

プロンプト

要件

• Anki 25.07以降 (Python 3.13同梱)

• Anki 25.02以前はPython 3.9を同梱しており、サポートされていません — MCP SDKはPython 3.10+を必要とします (#8)

アーキテクチャ

このアドオンは、HTTPトランスポート（FastMCP + uvicorn）を使用してバックグラウンドスレッドでMCPサーバーを実行します。すべてのAnki操作は、AnkiConnectと同じ実績のあるパターンに従い、キューシステムを介してメインのQtスレッドにブリッジされます。

詳細は Ankiアドオン開発ドキュメント を参照してください。

開発

E2Eテストの実行

E2Eテストは、headless-anki を使用してDocker内の実際のAnkiインスタンスに対して実行されます。

# Install test dependencies
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

# Build the addon
./package.sh

# Start Anki container
cd .docker && docker compose up -d && cd ..

# Run tests (waits for server automatically)
pytest tests/e2e/ -v

# Stop container
cd .docker && docker compose down

またはMakefileのショートカットを使用します：

make e2e        # Build, start container, run tests, stop
make e2e-up     # Just start container
make e2e-test   # Just run tests
make e2e-down   # Just stop container

CI

E2Eテストは、任意のブランチへのプッシュ時および main へのプルリクエスト時に自動的に実行されます。.github/workflows/e2e.yml を参照してください。

ライセンス

AGPL-3.0-or-later

リンク

• ankimcp.ai - プロジェクトホームページ

• MCP Protocol - Model Context Protocol仕様

• Anki Add-on Docs - 公式Ankiアドオン開発ドキュメント