Anki MCP Server

A Model Context Protocol (MCP) server that integrates with Anki flashcard application, allowing LLM applications like Claude to interact with your Anki decks and cards.

Features

• Card Management: Create, search, update, and delete flashcards
• Deck Management: List, create, and get statistics for decks
• Study Sessions: Get cards due for review and manage study sessions
• Model Support: Work with different note types and their fields
• Automatic Tagging: Cards created via MCP are automatically tagged with 'mcp-generated'

Prerequisites

1. Anki Desktop: Install Anki desktop application
2. AnkiConnect Plugin: Install the AnkiConnect plugin in Anki
   • Go to Tools → Add-ons → Get Add-ons
   • Enter code: 2055492159
   • Restart Anki

Installation

1. Clone this repository:

   git clone <repository-url>
   cd anki-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Usage

Running the Server

Start the MCP server:

npm start

For development with auto-reload:

npm run dev

Configuration with Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["/path/to/anki-mcp/dist/index.js"],
      "env": {
        "ANKI_HOST": "localhost",
        "ANKI_PORT": "8765"
      }
    }
  }
}

Available Tools

Connection Management

• test_connection: Test connection to AnkiConnect

Card Management

• create_card: Create a new flashcard
• search_cards: Search for cards using Anki query syntax
• update_card: Update existing card fields and tags
• delete_notes: Delete notes and their associated cards

Deck Management

• list_decks: List all available decks
• create_deck: Create a new deck
• get_deck_stats: Get statistics for a specific deck

Study Features

• get_cards_for_review: Get cards that are due for review
• get_model_names: List available note types/models
• get_model_fields: Get field names for a specific model

Example Usage in Claude

Once configured, you can use natural language commands in Claude:

• "Create a flashcard in my Spanish deck with 'hola' on the front and 'hello' on the back"
• "Search for all cards in the Spanish deck"
• "Show me cards that are due for review"
• "Create a new deck called 'French Vocabulary'"
• "What are the available note types in Anki?"

Environment Variables

• ANKI_HOST: AnkiConnect host (default: localhost)
• ANKI_PORT: AnkiConnect port (default: 8765)

Development

Scripts

• npm run build: Build TypeScript to JavaScript
• npm run dev: Run in development mode with auto-reload
• npm run watch: Watch mode for development
• npm test: Run tests
• npm run lint: Run ESLint

Project Structure

src/
├── index.ts          # Entry point
├── server.ts         # Main MCP server implementation
├── anki-client.ts    # AnkiConnect HTTP client
└── types/
    └── anki.ts       # TypeScript type definitions

Troubleshooting

Connection Issues

1. "Cannot connect to AnkiConnect":

   • Ensure Anki is running
   • Verify AnkiConnect plugin is installed
   • Check that AnkiConnect is listening on port 8765

2. "AnkiConnect error":

   • Check Anki error logs
   • Verify deck and model names exist
   • Ensure required fields are provided

Configuration Issues

1. Server not appearing in Claude:

   • Verify the path to the built JavaScript file is correct
   • Check Claude Desktop configuration syntax
   • Restart Claude Desktop after configuration changes

2. Permission Issues:

   • Ensure the Node.js process has permission to execute
   • Check file paths are absolute and correct

API Reference

The server implements the Model Context Protocol specification and provides tools for Anki integration. Each tool includes detailed input schemas and error handling.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request