# 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](https://apps.ankiweb.net/)** - Must be running during MCP server usage
2. **[AnkiConnect Add-on](https://ankiweb.net/shared/info/2055492159)** - 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:
```bash
npm install
```
Build the server:
```bash
npm run build
```
For development with auto-rebuild:
```bash
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:
```bash
npm install
```
3. Build the server:
```bash
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`
```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](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
```bash
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:
```bash
git clone https://github.com/YOUR_USERNAME/anki-mcp.git
cd anki-mcp
```
3. **Create a new branch** for your feature or bugfix:
```bash
git checkout -b feature/your-feature-name
```
4. **Make your changes** and test thoroughly
5. **Build and test** your changes:
```bash
npm install
npm run build
npm run inspector # Test with MCP Inspector
```
6. **Commit your changes** with clear, descriptive messages:
```bash
git commit -m "Add: description of your changes"
```
7. **Push to your fork**:
```bash
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](LICENSE) file for details.
## Acknowledgments
- Built on the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic
- Uses [AnkiConnect](https://foosoft.net/projects/anki-connect/) for Anki integration
- Powered by [yanki-connect](https://www.npmjs.com/package/yanki-connect) npm package
