anki-mcp-connector 0.1.2
A Model Context Protocol server for creating Anki flashcards via AnkiConnect
License: MIT
Requires Python: >=3.8
Keywords: anki, mcp, flashcards, ankiconnect, model-context-protocol

# Anki MCP Connector

A Model Context Protocol (MCP) server that enables AI assistants to create Anki flashcards programmatically via AnkiConnect.

## Overview

Anki MCP Connector provides a set of tools that allow MCP clients (like Claude Desktop) to interact with Anki, enabling automated flashcard creation and deck management. This makes it easy to create study materials directly from your conversations with AI assistants.

## Features

- 📚 **List all Anki decks** - Get all available decks in your Anki collection
- 🎴 **Get note type models** - Discover available card templates (Basic, Cloze, etc.)
- 🔍 **Inspect model fields** - See what fields are available for each note type
- ➕ **Create flashcards** - Add notes with custom fields, tags, and content
- 🏷️ **Automatic tagging** - All created cards are tagged with "Automatic" for easy filtering

## Prerequisites

1. **Anki** - Download and install from [ankiweb.net](https://apps.ankiweb.net/)
2. **AnkiConnect** - Install the AnkiConnect add-on for Anki:
   - Open Anki
   - Go to Tools → Add-ons → Get Add-ons
   - Enter code: `2055492159`
   - Restart Anki

AnkiConnect will run automatically whenever Anki is open, listening on `http://127.0.0.1:8765`.

## Installation

```bash
pip install anki-mcp-connector
```

## Usage

### With Claude Desktop

Add this to your Claude Desktop configuration file:

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

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "anki": {
      "command": "anki-mcp-connector"
    }
  }
}
```

Then restart Claude Desktop. With Anki running, you can now ask Claude to create flashcards!

### Example Conversations

```
You: "Create a flashcard with 'What is MCP?' on the front and 'Model Context Protocol' on the back in my 'Programming' deck"

You: "Add 5 vocabulary cards for common Spanish greetings to my Spanish deck"

You: "Create a cloze deletion card about Python list comprehensions"
```

## Available Tools

The MCP server exposes the following tools:

### `get_deck_list()`
Returns a list of all deck names in your Anki collection.

### `get_model_names()`
Returns available note type models (e.g., "Basic", "Basic (and reversed card)", "Cloze").

### `get_model_field_names(modelName: str)`
Returns the field names for a specific model.

**Example**: For "Basic" model, returns `["Front", "Back"]`

### `add_note(deckName: str, modelName: str, fields: dict, tags: list = None)`
Creates a new flashcard in the specified deck.

**Parameters**:
- `deckName`: Target deck name
- `modelName`: Note type to use
- `fields`: Dictionary mapping field names to content
- `tags`: Optional list of tags (always includes "Automatic")

**Example**:
```python
add_note(
    deckName="Japanese",
    modelName="Basic",
    fields={"Front": "こんにちは", "Back": "Hello"},
    tags=["greetings", "basic"]
)
```

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/anki-mcp-connector.git
cd anki-mcp-connector

# Install in development mode
pip install -e .
```

### Building

```bash
# Install build tools
pip install build twine

# Build the package
python -m build

# Upload to PyPI (requires credentials)
python -m twine upload dist/*
```

## Troubleshooting

### "Connection refused" errors
- Make sure Anki is running
- Verify AnkiConnect is installed (Tools → Add-ons)
- Check that AnkiConnect is listening on port 8765

### "Deck not found" errors
- Use `get_deck_list()` to see exact deck names (case-sensitive)
- Create the deck in Anki first if it doesn't exist

### Duplicate cards
The server prevents duplicates by default. If a card with the same content exists, you'll get an error.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Links

- [AnkiConnect Documentation](https://git.sr.ht/~foosoft/anki-connect)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Anki](https://apps.ankiweb.net/)

## Author

Tall Guy Jimmy

---

**Note**: This package requires Anki to be running with the AnkiConnect add-on installed. It communicates locally and does not send any data over the internet.