anki-mcp-server-integration

# Anki MCP Server Integration > Skill by [ara.so](https://ara.so) — MCP Skills collection. A Model Context Protocol (MCP) server that enables AI assistants to interact with Anki, the spaced repetition flashcard application. Transform study sessions into dynamic conversations where AI can create, edit, and review flashcards naturally, explain concepts, and adapt to your learning style. ## Installation ### Prerequisites - [Anki desktop app](https://apps.ankiweb.net/) installed and running - [AnkiConnect plugin](https://ankiweb.net/shared/info/2055492159) installed in Anki (Tools → Add-ons → Get Add-ons → code: 2055492159) - Node.js 20.19.0+ ### For Claude Desktop (STDIO Mode) **Option 1: MCPB Bundle (Recommended)** Download `.mcpb` file from [releases](https://github.com/ankimcp/anki-mcp-server/releases), then in Claude Desktop: - Settings → Extensions → drag and drop the `.mcpb` file - Configure AnkiConnect URL if needed (default: `http://localhost:8765`) - Restart Claude Desktop **Option 2: NPM Configuration** Add to `claude_desktop_config.json`: ```json { "mcpServers": { "anki-mcp": { "command": "npx", "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"], "env": { "ANKI_CONNECT_URL": "http://localhost:8765" } } } } ``` Location: - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` ### For Cursor IDE / Cline / Zed Add to MCP configuration file: ```json { "mcpServers": { "anki-mcp": { "command": "npx", "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"], "env": { "ANKI_CONNECT_URL": "http://localhost:8765" } } } } ``` Configuration locations: - Cursor: `~/.cursor/mcp.json` - Cline: VS Code settings UI - Zed: Extension marketplace ### For Web-based AI (HTTP Mode with ngrok) ```bash # One-time setup npm install -g @ankimcp/anki-mcp-server npm install -g ngrok ngrok config add-authtoken <YOUR_NGROK_TOKEN> # Start server with public tunnel ankimcp --ngrok ``` Share the ngrok URL with ChatGPT or Claude.ai as an MCP server endpoint. ## Configuration ### Environment Variables ```bash # AnkiConnect URL (default: http://localhost:8765) ANKI_CONNECT_URL=http://localhost:8765 # Enable read-only mode (no write operations) READ_ONLY=true ``` ### CLI Options ```bash ankimcp [options] --stdio # STDIO mode for MCP clients --port <port> # HTTP port (default: 3000) --host <host> # HTTP host (default: 127.0.0.1) --anki-connect <url> # AnkiConnect URL --ngrok # Start ngrok tunnel --read-only # Prevent modifications ``` ## Core Workflows ### 1. Interactive Review Session ```typescript // User says: "Help me review my Spanish deck" // AI workflow: // 1. Sync with AnkiWeb await use_mcp_tool({ server_name: "anki-mcp", tool_name: "sync", arguments: {} }); // 2. Get due cards from Spanish deck const dueCards = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "get_due_cards", arguments: { deck: "Spanish" } }); // 3. Present first card const presentation = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "present_card", arguments: { card_id: dueCards.cards[0].cardId } }); // AI shows question, user answers, then AI rates: await use_mcp_tool({ server_name: "anki-mcp", tool_name: "rate_card", arguments: { card_id: dueCards.cards[0].cardId, ease: 3 // 1=Again, 2=Hard, 3=Good, 4=Easy } }); ``` ### 2. Batch Card Creation ```typescript // User says: "Create 10 Arabic vocab cards with RTL styling" // 1. List available note types const models = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "modelNames", arguments: {} }); // 2. Get fields for Basic note type const fields = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "modelFieldNames", arguments: { modelName: "Basic" } }); // 3. Create notes in batch (up to 100 at once) const result = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "addNotes", arguments: { notes: [ { deckName: "Arabic::Vocabulary", modelName: "Basic", fields: { Front: "مرحبا", Back: "Hello" }, tags: ["arabic", "greetings"] }, { deckName: "Arabic::Vocabulary", modelName: "Basic", fields: { Front: "شكرا", Back: "Thank you" }, tags: ["arabic", "greetings"] } // ... up to 98 more notes ] } }); // Result includes successful IDs and any errors console.log(result.success); // [note_id1, note_id2, ...] console.log(result.errors); // Array of error objects if any failed ``` ### 3. Media Import from File ```typescript // User says: "Import this image from my Downloads folder into the selected note" // 1. Get selected note from Anki browser const selected = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "guiSelectedNotes", arguments: {} }); // 2. Upload media file (auto-detects file path) const media = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "storeMediaFile", arguments: { filename: "diagram.png", data: "/Users/username/Downloads/diagram.png" // File path (fastest) // OR url: "https://example.com/image.jpg" // URL download // OR data: "base64string..." // Base64 (slowest, avoid) } }); // 3. Get note details const noteInfo = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "notesInfo", arguments: { notes: [selected.result[0]] } }); // 4. Update front field with image await use_mcp_tool({ server_name: "anki-mcp", tool_name: "updateNoteFields", arguments: { note: { id: selected.result[0], fields: { Front: `<img src="${media.result}"> ${noteInfo.result[0].fields.Front.value}` } } } }); ``` ### 4. Deck Management ```typescript // List all decks with statistics const decks = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "listDecks", arguments: { includeStats: true } }); // Get detailed deck statistics const stats = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "deckStats", arguments: { decks: ["Spanish", "Spanish::Grammar"] } }); // Create nested deck (max 2 levels: Parent::Child) await use_mcp_tool({ server_name: "anki-mcp", tool_name: "createDeck", arguments: { deck: "French::Vocabulary" } }); // Move cards to different deck await use_mcp_tool({ server_name: "anki-mcp", tool_name: "changeDeck", arguments: { cards: [1234567890, 9876543210], deck: "French::Advanced" } }); ``` ### 5. Note Search and Update ```typescript // Search for notes using Anki query syntax const notes = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "findNotes", arguments: { query: "deck:Spanish tag:verb" // Anki search syntax } }); // Get detailed note information const noteDetails = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "notesInfo", arguments: { notes: notes.result } }); // Update note fields (CSS-aware, preserves formatting) await use_mcp_tool({ server_name: "anki-mcp", tool_name: "updateNoteFields", arguments: { note: { id: notes.result[0], fields: { Front: "¿Cómo estás?", Back: "How are you? (informal)" } } } }); // Delete notes and their cards await use_mcp_tool({ server_name: "anki-mcp", tool_name: "deleteNotes", arguments: { notes: [1234567890, 9876543210] } }); ``` ### 6. Tag Management ```typescript // Get all existing tags (use first to avoid duplication) const allTags = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "getTags", arguments: {} }); // Add tags to notes (space-separated) await use_mcp_tool({ server_name: "anki-mcp", tool_name: "addTags", arguments: { notes: [1234567890, 9876543210], tags: "important grammar advanced" } }); // Remove tags from notes await use_mcp_tool({ server_name: "anki-mcp", tool_name: "removeTags", arguments: { notes: [1234567890], tags: "beginner" } }); // Rename tag across all notes await use_mcp_tool({ server_name: "anki-mcp", tool_name: "replaceTags", arguments: { notes: [1234567890, 9876543210], tag_to_replace: "old-tag", replace_with_tag: "new-tag" } }); // Clean up unused tags from collection await use_mcp_tool({ server_name: "anki-mcp", tool_name: "clearUnusedTags", arguments: {} }); ``` ### 7. Media Management ```typescript // List media files with pattern filter const mediaFiles = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "getMediaFilesNames", arguments: { pattern: "*.png" } }); // Download media as base64 const mediaData = await use_mcp_tool({ server_name: "anki-mcp", tool_name: "retrieveMediaFile", arguments: { filename: "diagram.png" } }); // Upload media (three methods) // Method 1: File path (FASTEST - recommended) await use_mcp_tool({ server_name: "anki-mcp", tool_name: "storeMediaFile", arguments: { filename: "photo.jpg", data: "/Users/username/Pictures/photo.jpg" } }); // Method 2: URL (FAST - auto-downloads) await use_mcp_tool({ server_name: "anki-mcp", tool_name: "storeMediaFile", arguments: { filename: "diagram.png", url: "https://example.com/diagram.png" } }); // Method 3: Base64 (SLOW - avoid if possible) await use_mcp_tool({ server_name: "anki-mcp", tool_name: "storeMediaFile", arguments: { filename: "audio.mp3", data: "base64encodedstring..." }