genanki-mcp

🚀 genanki - MCP

本项目是一个自动化的Anki牌组生成服务，它基于 genanki 和 模型上下文协议（MCP） 构建。专注于可靠的牌组创建、严格的媒体沙盒机制，并保持简洁的工作流程，无多余冗余。

中文文档

✨ 主要特性

• 可流式传输的MCP HTTP工具，可接入任何符合MCP标准的客户端。
• 代理能够创建丰富的CSS模板，并安全地嵌入媒体资源。
• 提供临时下载链接（默认有效期600秒）用于获取 .apkg 文件。
• 媒体路径沙盒机制可防止越界文件访问和孤立资源的产生。

📦 项目结构

anki_mcp/
├── anki_tools/           # genanki实用工具包装器
│   └── genanki_tool.py
├── server/               # MCP + HTTP入口点
│   ├── anki_models.py    # Pydantic请求/响应模型
│   └── anki_server.py    # FastMCP / Starlette服务器
├── temp_anki_decks/      # 临时 .apkg 导出文件
├── .envexample           # 环境变量模板
├── pyproject.toml        # uv / pip 项目定义
└── uv.lock

🚀 快速开始

git clone https://github.com/Epiphany-0312/genanki-mcp.git
cd genanki-mcp

依赖要求

• Python ≥ 3.13
• 推荐使用 uv 进行依赖管理，也可使用 pip。

安装依赖

# 使用 uv（推荐）
uv sync

# 或者使用 pip
python -m venv .venv
.venv\Scripts\activate  # PowerShell
pip install -r requirements.txt

配置环境变量

将 .envexample 复制为 .env，并根据需要进行调整。

| 变量 | 描述 | 默认值 | | ---- | ---- | ---- | | PORT | Uvicorn/FastMCP 监听端口 | 10099 | | SREVERIP | 用于构建下载链接的公共IP/主机 | 127.0.0.1 | | TOKEN | 可选的Bearer令牌，用于保护工具访问 | （空） |

如果省略 TOKEN，服务将跳过身份验证。建议在生产环境中设置该变量。

运行服务

uv run python -m server.anki_server
# 或者
python -m server.anki_server

FastMCP 将在 http://0.0.0.0:<PORT>/anki 暴露工具，并在 http://0.0.0.0:<PORT>/downloads 提供临时下载服务。

💻 使用示例

可连接任何支持MCP的客户端。默认情况下，MCP端点监听 http://127.0.0.1:10099/anki。

以下是Cherry Studio的示例配置和工作流程：

📄 许可证

本项目采用MIT许可证。