Anki MCP Server

Anki MCP 服务

概述

本项目提供一个 Model Context Protocol（MCP）服务，通过 Anki-Connect 插件作为桥梁，连接到间隔重复软件 Anki。它允许兼容 MCP 的客户端（例如 AI 助手或其他应用程序）与您的 Anki 收藏集交互，管理牌组、卡片和笔记。

功能

• 将全面的 Anki 操作作为 MCP 工具提供。
• 管理与本地 Anki-Connect 实例的通信。
• 提供以下工具：
  • 牌组管理（列出、创建、删除、移动卡片、获取统计数据）
  • 卡片管理（查找、获取信息、暂停、取消暂停、检查状态、忘记、重新学习）
  • 笔记管理（添加、更新、查找、获取信息、管理标签、删除）
  • 模型管理（列出名称、列出字段）
  • 其他操作（请求权限、获取版本、同步）

前提条件

1. Anki： 您必须在系统上安装并运行 Anki。
2. Anki-Connect 插件： 必须在 Anki 中安装并运行 Anki-Connect 插件。默认情况下，它监听 http://127.0.0.1:8765。
3. Python： 兼容的 Python 版本（见 pyproject.toml）。
4. uv： 推荐用于管理 Python 环境和依赖项（uv 安装指南）。

安装

1. 克隆仓库：

   git clone <repository-url> # Replace with the actual URL if applicable
   cd anki-mcp-server
   

2. 安装依赖项：

   uv sync
   

运行服务

启动服务前，请确保 Anki 正在运行且已启用 Anki-Connect 插件。

您可以通过以下几种方式运行服务：

1. 直接执行（使用 uv）：

   uv run python main.py
   

   这将使用 stdio 传输启动服务，适用于直接集成或测试。

2. 开发模式（使用 MCP Inspector）：

   uv run mcp dev main.py
   

   这会启动服务并打开 MCP Inspector 工具，让您可以交互式地测试可用的工具和资源。

3. 安装到 Claude Desktop：

   uv run mcp install main.py --name "Anki Bridge"
   

   这会将服务安装到 Claude Desktop（如果可用），以便在助手中使用 Anki 工具。

使用方法

服务运行并连接到 MCP 客户端（例如通过 mcp install 连接的 Claude Desktop，或使用 MCP 协议的其他应用程序）后：

1. 请求权限： 通常应首先调用 anki_request_permission。如果 Anki-Connect 不信任客户端的来源，Anki 中会弹出确认窗口。
2. 使用工具： 调用可用工具（如下所列）与您的 Anki 收藏集交互。

配置

• Anki-Connect URL： 服务使用 main.py 中 ANKICONNECT_URL 常量定义的 URL 连接到 Anki-Connect（默认值：http://127.0.0.1:8765）。如果您的 Anki-Connect 配置使用了不同的地址或端口，请修改此值。

可用工具

服务提供以下工具，对应 Anki-Connect API 操作：

牌组操作

• anki_deck_names：获取完整的牌组名称列表。
• anki_deck_names_and_ids：获取牌组名称及其 ID。
• anki_create_deck(deck_name: str)：创建一个新的空牌组。
• anki_change_deck(card_ids: List[int], deck_name: str)：将卡片移至其他牌组。
• anki_delete_decks(deck_names: List[str])：删除指定的牌组及其中的卡片。
• anki_get_deck_stats(deck_names: List[str])：获取指定牌组的统计信息。

卡片操作

• anki_find_cards(query: str)：使用 Anki 搜索查询查找卡片。
• anki_cards_info(card_ids: List[int])：获取多张卡片的详细信息。
• anki_cards_to_notes(card_ids: List[int])：获取指定卡片 ID 对应的笔记 ID。
• anki_suspend_cards(card_ids: List[int])：暂停指定的卡片。
• anki_unsuspend_cards(card_ids: List[int])：取消暂停指定的卡片。
• anki_are_suspended(card_ids: List[int])：检查卡片是否已暂停。
• anki_are_due(card_ids: List[int])：检查卡片是否到了复习时间。
• anki_forget_cards(card_ids: List[int])：将指定的卡片重置为新卡片。
• anki_relearn_cards(card_ids: List[int])：将指定的卡片设为重新学习状态。

笔记操作

• anki_add_note(...)：使用指定的牌组、模型、字段、选项、标签和媒体创建新的 Anki 笔记。
• anki_update_note_fields(...)：修改现有笔记的字段和媒体。
• anki_find_notes(query: str)：使用 Anki 搜索查询查找笔记。
• anki_notes_info(note_ids: List[int])：获取多条笔记的详细信息。
• anki_get_note_tags(note_id: int)：获取指定笔记的标签。
• anki_add_tags(note_ids: List[int], tags: str)：为笔记添加以空格分隔的标签。
• anki_remove_tags(note_ids: List[int], tags: str)：从笔记中移除以空格分隔的标签。
• anki_update_note_tags(note_id: int, tags: List[str])：设置笔记的标签，替换原有标签。
• anki_delete_notes(note_ids: List[int])：删除指定的笔记及其卡片。

模型操作

• anki_model_names()：获取模型（笔记类型）名称列表。
• anki_model_field_names(model_name: str)：获取指定模型的字段名称列表。

其他操作

• anki_request_permission()：请求使用 Anki-Connect API 的权限。应首先调用。
• anki_version()：获取 Anki-Connect API 的版本。
• anki_sync()：将本地 Anki 收藏与 AnkiWeb 同步。

参与贡献

欢迎贡献！请参阅项目的贡献指南（如果有）。

许可证

注明本项目采用的许可证（例如，MIT License）。