我的Anki MCP
Anki的模型上下文协议（MCP）服务器-使AI助手能够与您的Anki闪卡进行交互。
](https://www.npmjs.com/package/@laomeifun/my-anki-mcp)
Seamlessly integrate Anki with AI assistants through the Model Context Protocol
贝塔 -该项目正在积极开发中。API和功能可能会发生变化。
一个模型上下文协议（MCP）服务器，使AI助手能够与间隔重复闪存卡应用程序Anki进行交互。
通过自然语言交互改变您的Anki体验。
可用工具
回顾与研究
sync-与AnkiWeb同步get_due_cards-获取卡片以供审核present_card-出示卡片以供审核rate_card-价目表性能
甲板管理
list_decks-显示可用甲板createDeck-创建新甲板
笔记管理
addNote-创建新笔记findNotes-使用Anki查询语法搜索笔记notesInfo-获取有关注释（字段、标签、CSS）的详细信息updateNoteFields-更新现有注释字段（支持CSS，支持HTML）deleteNotes-删除笔记及其卡片
媒体管理
mediaActions-管理媒体文件（音频/图像）
- storeMediaFile -从base64数据、文件路径或URL上传媒体 - retrieveMediaFile -以base64格式下载媒体 - getMediaFilesNames -列出具有可选模式过滤的媒体文件 - deleteMediaFile -删除媒体文件
💡 图像的最佳实践：
- ✅ 使用文件路径 （例如。，
/Users/you/image.png)-快速高效 - ✅ 使用URL （例如。，
https://example.com/image.jpg)-直接下载 - ❌ 避免使用base64 -速度极慢，效率极低
只需告诉Claude图像在哪里，它就会使用最有效的方法自动处理上传。
模型/模板管理
modelNames-列出注释类型modelFieldNames-获取笔记类型的字段modelStyling-获取注释类型的CSS样式
先决条件
- Node.js 20+
安装
此服务器以两种模式工作：
- 本地模式（STDIO） -适用于您计算机上的Claude Desktop（建议大多数用户使用）
- 远程模式（HTTP） -适用于基于网络的AI助手，如ChatGPT或Claude.AI
选项1:MCPB捆绑包（推荐-本地模式）
为Claude Desktop安装此MCP服务器的最简单方法：
- 下载最新
.mcpb捆绑从 发布 页 - 在Claude Desktop中，安装扩展：
- 方法1：转到设置→ 扩展，然后拖放 .mcpb 文件 - 方法2：转到设置→ 开发者→ 扩展→ 安装扩展，然后选择 .mcpb 文件
- 如果需要，配置AnkiConnect URL（默认为
http://localhost:8765) - 重新启动克劳德桌面
就是这样！该捆绑包包括在本地运行服务器所需的一切。
选项2：带STDIO的NPM包（适用于其他MCP客户端）
想在MCP客户端上使用Anki，比如 光标IDE, 克莱恩，或 Zed编辑？使用npm包 --stdio 标志：
支持的客户端：
配置-选择一种方法：
方法1：使用npx（推荐-无需安装）
{
"mcpServers": {
"anki-mcp": {
"command": "npx",
"args": ["-y", "@laomeifun/my-anki-mcp", "--stdio"],
"env": {
"ANKI_CONNECT_URL": "http://localhost:8765"
}
}
}
}方法2：使用全局安装
首先，全局安装：
npm install -g @laomeifun/my-anki-mcp然后配置：
{
"mcpServers": {
"anki-mcp": {
"command": "ankimcp",
"args": ["--stdio"],
"env": {
"ANKI_CONNECT_URL": "http://localhost:8765"
}
}
}
}配置文件位置：
- 光标IDE:
~/.cursor/mcp.json（macOS/Linux）或%USERPROFILE%\.cursor\mcp.json（Windows） - 克莱恩：可通过VS Code中的设置UI访问
- Zed编辑：通过扩展市场安装为MCP扩展
有关客户特定的功能和故障排除，请参阅MCP客户的文档。
选项3:HTTP模式（适用于远程AI助理）
想在浏览器中使用Anki和ChatGPT或Claude.ai吗？此模式允许您将基于web的AI工具连接到本地Anki。
它是如何工作的（简单解释）：
- 您在安装了Anki的计算机上运行一个小型服务器
- 使用内置
--ngrok用于自动创建公共隧道URL的标志 - 与ChatGPT或Claude.ai共享该URL
- 现在AI可以通过互联网与你的Anki对话了！
v0.8.0中的新功能： 与集成的ngrok支持 --ngrok 旗帜-不需要单独运行ngrok！
设置-选择一种方法：
方法1：使用npx（推荐-无需安装）
# Quick start
npx @laomeifun/my-anki-mcp
# With ngrok tunnel (recommended for web-based AI)
npx @laomeifun/my-anki-mcp --ngrok
# With custom options
npx @laomeifun/my-anki-mcp --port 8080 --host 0.0.0.0
npx @laomeifun/my-anki-mcp --anki-connect http://localhost:8765方法2：使用全局安装
# Install once
npm install -g @laomeifun/my-anki-mcp
# Run the server
ankimcp
# With ngrok tunnel (recommended for web-based AI)
ankimcp --ngrok
# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765方法3：从源代码安装（用于开发）
npm install
npm run build
npm run start:prod:httpCLI选项：
ankimcp [options]
Options:
--stdio Run in STDIO mode (for MCP clients)
-p, --port
Port to listen on (HTTP mode, default: 3000)
-h, --host Host to bind to (HTTP mode, default: 127.0.0.1)
-a, --anki-connect AnkiConnect URL (default: http://localhost:8765)
--ngrok Start ngrok tunnel (requires global ngrok installation)
--help Show help message
Usage with npx (no installation needed):
npx @laomeifun/my-anki-mcp # HTTP mode
npx @laomeifun/my-anki-mcp --port 8080 # Custom port
npx @laomeifun/my-anki-mcp --stdio # STDIO mode
npx @laomeifun/my-anki-mcp --ngrok # HTTP mode with ngrok tunnel
Usage with global installation:
npm install -g @laomeifun/my-anki-mcp # Install once
ankimcp # HTTP mode
ankimcp --port 8080 # Custom port
ankimcp --stdio # STDIO mode
ankimcp --ngrok # HTTP mode with ngrok tunnel与ngrok一起使用：
方法1：集成（推荐-一个命令）
# One-time setup (if you haven't already):
npm install -g ngrok
ngrok config add-authtoken # Get token from https://dashboard.ngrok.com
# Start server with ngrok tunnel in one command:
ankimcp --ngrok
# The tunnel URL will be displayed in the startup banner
# Example output:
# 🌐 Ngrok tunnel: https://abc123.ngrok-free.app方法2：手动（双端子）
# Terminal 1: Start the server
ankimcp
# Terminal 2: Create tunnel
ngrok http 3000
# Copy the ngrok URL (looks like: https://abc123.ngrok-free.app)
# Share this URL with your AI assistant益处 --ngrok 标志：
- ✅ 一个命令而不是两个终端
- ✅ 按Ctrl+C时自动清理
- ✅ 直接显示在启动横幅中的URL
- ✅ 适用于自定义端口：
ankimcp --port 8080 --ngrok
安全说明： 任何拥有你的ngrok URL的人都可以访问你的Anki，所以请将该URL保密！
选项4：从源手动安装（本地模式）
用于开发或高级使用：
npm install
npm run build连接到克劳德桌面（本地模式）
您可以通过以下任一方式在Claude Desktop中配置服务器：
- 转到：设置→ 开发者→ 编辑配置
- 或者手动编辑配置文件
配置
将以下内容添加到您的Claude Desktop配置中：
{
"mcpServers": {
"anki-mcp": {
"command": "node",
"args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
"env": {
"ANKI_CONNECT_URL": "http://localhost:8765"
}
}
}
}替换 /path/to/anki-mcp-server 根据您的实际项目路径。
配置文件位置
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
有关更多详细信息，请参阅 MCP官方文件.
环境变量（可选）
| 变量 | 描述 | 默认值 |
|---|---|---|
ANKI_CONNECT_URL | AnkiConnect URL | http://localhost:8765 |
ANKI_CONNECT_API_VERSION | API版本 | 6 |
ANKI_CONNECT_API_KEY | API密钥（如果在AnkiConnect中配置） | - |
ANKI_CONNECT_TIMEOUT | 请求超时（毫秒） | 5000 |
用法示例
搜索和更新笔记
# Search for notes in a specific deck
findNotes(query: "deck:Spanish")
# Get detailed information about notes
notesInfo(notes: [1234567890, 1234567891])
# Update a note's fields (HTML content supported)
updateNoteFields(note: {
id: 1234567890,
fields: {
"Front": "¿Cómo estás?",
"Back": "How are you?"
}
})
# Delete notes (requires confirmation)
deleteNotes(notes: [1234567890], confirmDeletion: true)Anki查询语法示例
这 findNotes 该工具支持Anki强大的查询语法：
"deck:DeckName"-特定套牌中的所有笔记"tag:important"-带有“重要”标签的注释"is:due"-应审核的卡片"is:new"-尚未研究的新卡片"added:7"-最近7天添加的注释"front:hello"-前栏有“hello”的注释"flag:1"-带有红旗的注释"prop:due 6.3（取决于WebStorm版本）
- 点击 好的
- 点击 调试 （Shift+F9）进行连接
VS Code
- 增添
.vscode/launch.json:
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "attach",
"name": "Attach to Anki MCP (Claude Desktop)",
"port": 9229,
"skipFiles": ["/**"],
"sourceMaps": true,
"outFiles": ["${workspaceFolder}/dist/**/*.js"]
}
]
}- 打开调试面板（Ctrl+Shift+D/Cmd+Shift+D）
- 选择 连接到Anki MCP（克劳德桌面）
- 按F5连接
步骤4：实时调试
一旦连接，您可以：
- 在TypeScript源文件中设置断点（例如。，
src/mcp/primitives/essential/tools/create-model.tool.ts) - 正常使用Claude Desktop-调用工具时会触发断点
- 逐步执行代码
- 检查变量并调用堆栈
- 使用调试控制台
示例：在中设置断点 create-model.tool.ts 在第119行，然后让Claude创建一个新模型。调试器将在您的断点处暂停！
备注：只要Claude Desktop正在运行，调试器就会保持连接状态。您可以随时分离/重新连接，而无需重新启动Claude Desktop。
构建命令
npm run build # Build the project (compile TypeScript to JavaScript)
npm run start:dev:stdio # STDIO mode with watch (auto-rebuild)
npm run start:dev:http # HTTP mode with watch (auto-rebuild)
npm run type-check # Run TypeScript type checking
npm run lint # Run ESLint
npm run mcpb:bundle # Sync version, clean, build, and create MCPB bundleNPM包测试（本地）
在发布之前在本地测试npm包：
# 1. Create local package
npm run pack:local # Builds and creates @laomeifun/my-anki-mcp-*.tgz
# 2. Install globally from local package
npm run install:local # Installs from ./@laomeifun/my-anki-mcp-*.tgz
# 3. Test the command
ankimcp # Runs HTTP server on port 3000
# 4. Uninstall when done testing
npm run uninstall:local # Removes global installation它是如何工作的：
npm pack创建a.tgz与npm publish创建的文件相同- 从安装
.tgz模拟用户从中获得的内容npm install -g @laomeifun/my-anki-mcp - 这使您可以在发布到npm之前测试完整的用户体验
测试命令
npm test # Run all tests
npm run test:unit # Run unit tests only
npm run test:tools # Run tool-specific tests
npm run test:workflows # Run workflow integration tests
npm run test:e2e # Run end-to-end tests
npm run test:cov # Run tests with coverage report
npm run test:watch # Run tests in watch mode
npm run test:debug # Run tests with debugger
npm run test:ci # Run tests for CI (silent, with coverage)测试覆盖率
该项目为以下项目保持了70%的最低覆盖阈值：
- 分支
- 函数
- 线条
- 声明
覆盖率报告在 coverage/ 目录。
版本控制
该项目如下 语义化版本 采用1.0之前的开发方法：
- 0.x.x -测试版/开发版（当前阶段）
- 0.1.x -Bug修复和补丁 - 0.2.0+ -新功能或细微改进 - 突破性变化 在0.x版本中是可以接受的
- 1.0.0 -首次稳定发布
- 将在API稳定并经过测试后发布 - 重大更改将需要重大版本升级（2.0.0等）
当前状态: 0.8.0 -积极的beta开发。新功能包括集成的ngrok隧道(--ngrok 旗） twenty_rules 提示循证抽认卡制作、媒体文件管理，完善提示系统。API可能会根据反馈和测试而变化。
类似项目
如果您正在探索Anki MCP集成，以下是该领域的其他项目：
scorzeth/anki mcp服务器
- 状态：似乎已被放弃（没有最近的更新）
- Anki MCP集成的早期实施
nailuoGG/anki mcp服务器
- 方法：轻量级的单文件实现
- 建筑：在一个文件中包含所有工具的过程代码结构
- 很好：简单的用例，最小的依赖性
为什么这个项目不同：
- 企业级架构：基于NestJS构建，带有依赖注入
- 模块化设计：每个工具都是一个单独的类，具有明确的关注点分离
- 可维护性：易于扩展新功能，无需接触现有代码
- 测试：全面的测试套件，覆盖率要求为70%
- 类型安全性：带有Zod验证的严格TypeScript
- 错误处理：强大的错误处理能力和有用的用户反馈
- 生产就绪：适当的日志记录、进度报告和MCPB捆绑包支持
- 可扩展性：可以轻松地从基本工具扩展到复杂的工作流程
用例：如果你需要一个坚实的基础来构建高级Anki集成，或者计划大幅扩展功能，这个项目的架构方法使其更容易维护和扩展。
实用链接
许可和归属
本项目根据GNU Affero通用公共许可证v3.0或更高版本（AGPL-3.0或更高）获得许可。
为什么选择AGPL-3.0？
选择此许可证是为了在未来的潜在集成场景中保持与Anki的AGPL-3.0许可证的兼容性。
这意味着：
- 个人使用：自由使用软件
- 为他人提供服务：您必须提供源代码访问权限（AGPL第13节）
- 修改和分发：在AGPL-3.0或更高版本下分享您的改进
有关完整的许可条款，请参阅 许可证 文件。
第三方归因
- Anki® 是Ankitects Pty有限公司的注册商标。该项目是一个非官方的第三方工具，不隶属于、认可或赞助Ankitecs Pty有限公司。Anki徽标是在替代许可证下使用的，用于引用Anki，链接到 https://apps.ankiweb.net如需Anki的官方申请，请访问 https://apps.ankiweb.net.
- 这是一个连接Anki和MCP技术的独立项目。所有商标、服务标志、商品名、产品名称和徽标均为其各自所有者的财产。