Anki MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Anki, enabling AI assistants to interact with your flashcard collection. Create, read, update, and manage Anki cards programmatically through a standardized interface.

Features

• 🎴 Card Management: Create, retrieve, and update flashcards with full field customization
• 🔍 Smart Search: Query cards by ID, keywords, tags, decks, or any Anki search syntax
• 📊 Review Integration: Access due cards, new cards, and answer cards programmatically
• 🎵 Media Support: Automatic handling of audio and images (local files, URLs, or existing media)
• 🔄 Batch Operations: Create multiple cards efficiently in a single operation
• 🎯 Generic Tools: Flexible tools that work with any deck, note type, and field configuration

Prerequisites

1. Anki Desktop App - Must be running during MCP server usage
2. AnkiConnect Add-on - Install from Anki: Tools → Add-ons → Get Add-ons → Code: 2055492159

⚠️ Important: Anki must be running with AnkiConnect enabled for this MCP server to function.

Resources

• anki://search/deckcurrent - All cards from current deck
• anki://search/isdue - Cards due for review
• anki://search/isnew - New unseen cards
• Custom queries: anki://search/tag:vocabulary, anki://search/deck:Spanish, etc.

Tools

• update_card - Update cards/notes (answer, update fields, update tags)
• add_card - Create a new flashcard with custom deck, model, and fields
• batch_add_card - Create multiple flashcards at once
• get_due_cards - Get list of cards due for review
• get_new_cards - Get list of new unseen cards
• get_card - Retrieve detailed card information by ID or query

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Media Files

How Media Files Are Handled

When you add cards with images or audio files, the server automatically handles different types of media sources:

1. Local File Paths: If you provide an absolute path to a file on your computer (e.g., /Users/vu.letuan/Documents/vu/English/images/prune.jpg), the server will:

   • Read the file from your disk
   • Convert it to base64
   • Upload it to Anki's media collection using the storeMediaFile API
   • Reference it in the card by filename

2. URLs: If you provide a URL (e.g., https://example.com/image.jpg), Anki-Connect will download the file automatically when the card is created.

3. Existing Media: If you provide just a filename (e.g., prune.jpg), it assumes the file already exists in Anki's media folder.

Troubleshooting Image Issues

If images don't show up properly in Anki:

1. Check the file path: Make sure the path to your image file is correct and the file exists
2. File permissions: Ensure the file is readable by the application
3. Supported formats: Anki supports common image formats (JPG, PNG, GIF, SVG, WebP)
4. File size: Very large files might cause issues
5. Special characters: Avoid special characters in filenames when possible

The server will now automatically handle local file paths, so you don't need to manually copy images to Anki's media folder anymore.

Installation & Configuration

Installation

1. Clone or download this repository
2. Install dependencies:

   npm install
   

3. Build the server:

   npm run build
   

Configuration with Claude Desktop

Add the server configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "anki-mcp-server": {
      "command": "/absolute/path/to/anki-mcp-server/build/index.js"
    }
  }
}

💡 Tip: Replace /absolute/path/to/anki-mcp-server with the actual full path to where you cloned this repository.

Configuration with Other MCP Clients

This server follows the standard MCP protocol and can be used with any MCP-compatible client. Configure it as a stdio-based server pointing to build/index.js.

Verification

After configuration:

1. Restart Claude Desktop (or your MCP client)
2. Ensure Anki is running with AnkiConnect installed
3. The server should appear in your available MCP servers
4. Test with a simple query like "Show me 5 due cards from Anki"

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser where you can:

• Test tool calls interactively
• View request/response logs
• Debug connection issues
• Validate tool schemas

Troubleshooting

Server not appearing in Claude Desktop:

• Verify the path in config is absolute (not relative)
• Check that build/index.js exists (run npm run build)
• Restart Claude Desktop after config changes

"Connection refused" or timeout errors:

• Ensure Anki is running
• Verify AnkiConnect is installed (Tools → Add-ons)
• Check AnkiConnect settings allow localhost connections (default)

Cards not updating/creating:

• Close the Anki browser if you have it open (known AnkiConnect limitation)
• Verify the deck and note type names match exactly (case-sensitive)
• Check field names match your note type's field configuration

Contributing

Contributions are welcome! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

How to Contribute

1. Fork the repository on GitHub
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/anki-mcp.git
   cd anki-mcp
   

3. Create a new branch for your feature or bugfix:

   git checkout -b feature/your-feature-name
   

4. Make your changes and test thoroughly
5. Build and test your changes:

   npm install
   npm run build
   npm run inspector  # Test with MCP Inspector
   

6. Commit your changes with clear, descriptive messages:

   git commit -m "Add: description of your changes"
   

7. Push to your fork:

   git push origin feature/your-feature-name
   

8. Open a Pull Request on GitHub with a clear description of your changes

Development Guidelines

• Write clean, readable TypeScript code
• Follow the existing code style and structure
• Test your changes with the MCP Inspector
• Update documentation if you're adding new features
• Keep commits focused and atomic

Reporting Issues

Found a bug or have a feature request? Please open an issue on GitHub with:

• A clear, descriptive title
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Your environment (OS, Anki version, Node version)

Questions?

Feel free to open an issue for questions or join the discussion in existing issues.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built on the Model Context Protocol by Anthropic
• Uses AnkiConnect for Anki integration
• Powered by yanki-connect npm package