Anki Model Context Protocol (MCP) Server

一个高性能的 Model Context Protocol (MCP) 服务器，使 Claude Desktop、Claude Code、Antigravity、Codex、Cursor 等 AI 助手能够直接管理 Anki 卡片、牌组、笔记、笔记类型、标签、媒体和搜索。

⚡ 通用基于文件的 I/O 架构

现代卡片（尤其是带有 HTML 标记、语法高亮代码块和 LaTeX 数学公式的卡片）？实际上应为：，这些卡片的负载很大. 通过 JSON-RPC 工具参数流式传输这些内容，或将完整卡片内容直接返回给模型，会导致 token 耗尽、输出被截断以及上下文窗口饱和。

本服务器实现了 通用基于文件的输入和输出（File-Based I/O）：

1. 零带内 Token 膨胀： 卡片变更、查询、搜索和架构自省均接受输入 JSON 文件路径，并将完整的结构化输出写入磁盘。

2. 紧凑的遥测响应： 每次工具调用都会返回小型的元数据摘要（$< 150$ 个 token），其中包含状态、ID、受影响数量和已解析的 output_file 路径。

3. 原子批量导入： 可将数百张卡片写入单个 JSON 负载，并在一个原子的 SQLite 事务中毫秒级导入。

4. 跨平台临时存储： 输出默认写入操作系统临时目录（Windows 为 %TEMP%\anki_mcp，Linux/macOS 为 /tmp/anki_mcp），可通过 ANKI_MCP_OUTPUT_DIR 进行覆盖。

Related MCP server: Anki MCP Server

功能

• ⚡ 快速直连桥接： 通过官方 anki Python 引擎直接与 Anki 的收藏数据库（collection.anki2）交互，零 HTTP 开销。

• 🔒 非阻塞连接生命周期： 使用按请求的打开/关闭上下文机制（~2.7ms），因此数据库锁会被立即释放，且不会锁住 Anki Desktop。

• 🪟 跨平台： 原生支持 Windows、macOS 和 Linux，并自动发现标准操作系统位置的收藏集合。

• 🗂️ 分层牌组： 全面支持嵌套牌组创建（例如 Computer Science::Algorithms::Trees）。

• 📝 丰富的卡片格式： 支持标准/基础卡片、挖空题（{{c1::...}}）、自定义字段以及 LaTeX 数学公式（$...$ 和 $$...$$）。

• 🔍 查询引擎： 完全支持 Anki 的搜索语法（deck:Languages tag:grammar、is:due、added:7、"Recursion"）。

• 🏷️ 标签管理： 支持分层标签及批量添加/移除标签。

• 📦 批量创建： 通过 JSON 负载在单个原子操作中高吞吐量批量添加卡片。

• 💾 牌组导出： 原生打包为 .apkg、.colpkg 和 .json。

• 💡 MCP 提示词与资源： 内置资源（anki://decks、anki://stats）和结构化卡片生成提示词（flashcard_generator）。

安装与设置

本项目使用 uv 来管理快速且可复现的 Python 环境。

克隆并安装

git clone https://github.com/debnath-d/anki-mcp-server.git
cd anki-mcp-server
uv sync

运行服务器

uv run anki-mcp-server

客户端配置

1. Claude Desktop

将服务器添加到你的 Claude Desktop 配置文件中：

• Windows： %APPDATA%\Claude\claude_desktop_config.json

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux： ~/.config/Claude/claude_desktop_config.json

Windows 配置

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\anki-mcp-server",
        "run",
        "anki-mcp-server"
      ]
    }
  }
}

macOS / Linux 配置

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/anki-mcp-server",
        "run",
        "anki-mcp-server"
      ]
    }
  }
}

2. Google Antigravity

移除 Antigravity 的 MCP 时，请先进入 Google Antigravity，并打开 MCP 配置文件（~/.gemini/config/mcp_config.json）：

{
  "mcpServers": {
    "anki": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/anki-mcp-server",
        "run",
        "anki-mcp-server"
      ]
    }
  }
}

3. Claude Code / Codex / CLI 客户端

通过 MCP 服务器启动 Claude Code：

claude --mcp-server "uv --directory '/path/to/anki-mcp-server' run anki-mcp-server"

可用的 MCP 工具

1. 牌组管理

2. 笔记类型（模型）

3. 卡片与笔记管理（基于文件）

4. 媒体、状态控制与导出

5. 搜索与发现

6. 标签管理与统计

测试

运行自动化测试套件和 linter：

ruff check .
uv run python -m unittest discover -s tests

重要说明与故障排除

1. SQLite 数据库锁： Anki 使用排他文件锁。在 MCP 服务器执行写入操作期间，必须关闭 Anki 桌面 GUI 应用程序，以防止出现 anki.errors.DBError 锁错误。

2. 集合路径自动发现：

   • Windows： 自动在 ~/.local/share/Anki2/<Profile>/collection.anki2 或 ~/.local/share/Anki2/<Profile>/collection.anki2 中检测。

   • macOS： 自动在 ~/Library/Application Support/Anki2/<Profile>/collection.anki2 中检测。

   • Linux： 自动在 ~/.local/share/Anki2/<Profile>/collection.anki2 中检测。

   • 如需使用自定义位置，请设置 ANKI_COLLECTION_PATH 环境变量。

3. 输出缓存： 默认情况下，工具输出存储在操作系统的临时目录（%TEMP%\anki_mcp 或 /tmp/anki_mcp）中。如需使用自定义目录，请设置 ANKI_MCP_OUTPUT_DIR 环境变量。

Wait, I made an error in the Windows line — I accidentally duplicated the Linux path. Let me correct that:

1. SQLite 数据库锁： Anki 使用排他文件锁。在 MCP 服务器执行写入操作期间，必须关闭 Anki 桌面 GUI 应用程序，以防止出现 anki.errors.DBError 锁错误。

2. 集合路径自动发现：

   • Windows： 自动在 %APPDATA%\Anki2\<Profile>\collection.anki2 或 %LOCALAPPDATA%\Anki2\<Profile>\collection.anki2 中检测。

   • macOS： 自动在 ~/Library/Application Support/Anki2/<Profile>/collection.anki2 中检测。

   • Linux： 自动在 ~/.local/share/Anki2/<Profile>/collection.anki2 中检测。

   • 如需使用自定义位置，请设置 ANKI_COLLECTION_PATH 环境变量。

3. 输出缓存： 默认情况下，工具输出存储在操作系统的临时目录（%TEMP%\anki_mcp 或 /tmp/anki_mcp）中。如需使用自定义目录，请设置 ANKI_MCP_OUTPUT_DIR 环境变量。