AnkiMCP Server

AnkiMCP服务器（插件）

Seamlessly integrate Anki with AI assistants through the Model Context Protocol

Anki插件，通过 模型上下文协议（MCP）.

这是什么？

AnkiMCP服务器在Anki内部运行一个本地MCP服务器，允许像Claude这样的人工智能助手与您的闪卡收藏进行交互。这使得人工智能支持的学习课程、卡片创建和收藏管理成为可能。

部分 ankimcp.ai 项目。

首次运行注意事项

首次运行时，此插件会下载 pydantic_core （~2MB）来自PyPI。这是必需的，因为pydantic_core包含无法捆绑在单个插件文件中的特定于平台的二进制文件（Windows/MOSC/Linux）。

特性

• 本地HTTP服务器 -继续运行 http://127.0.0.1:3141/ 默认情况下
• MCP协议 -兼容任何MCP客户端（克劳德桌面等）
• 自动启动 -Anki打开时服务器自动启动
• 隧道友好型 -与Cloudflare Tunnel、ngrok等合作。
• 跨平台 -适用于macOS、Windows和Linux（x64和ARM）

安装

来自AnkiWeb（推荐）

1. 打开Anki并转到 *工具→ 附加组件→ 获取附加组件。..*
2. 输入代码： 124672614
3. 重新启动Anki

来自GitHub发布

1. 下载 anki_mcp_server.ankiaddon 从 发布
2. 双击安装或使用 *工具→ 附加组件→ 从文件安装。..*
3. 重新启动Anki

NixOS 系统

带薄片（推荐）

添加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 ])
    ];
  };
}

无薄片

# 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服务器设置。..*

与克劳德桌面连接

需要 安装。添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

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

注： Claude Desktop在JSON配置中不支持HTTP服务器-- mcp-remote 通过stdio桥接连接。

与克劳德代码连接

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

配置

通过Anki编辑 *工具→ 附加组件→ AnkiMCP服务器→ 配置*:

{
  "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客户端（如网络托管的MCP检查器），请添加允许的源：

{
  "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类型检查仅限于媒体文件（图像、音频、视频）
• 网址 必须使用 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操作都通过队列系统桥接到主Qt线程，遵循与AnkiConnect相同的经过验证的模式。

有关详细信息，请参阅 Anki插件开发文档.

发展

运行E2E测试

E2E测试在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测试在任何分支和PR上自动运行 main。参见 .github/workflows/e2e.yml.

许可证

AGPL-3.0或更高版本

链接

• ankimcp.ai -项目主页
• MCP协议 -模型上下文协议规范
• Anki附加文件 -官方Anki插件开发文档