# Anki Flashcard MCP Server 🃏

## Project Overview 🚀

This project provides a **Dockerized Model Context Protocol (MCP)** server specifically designed to work with the **Anki** desktop application. By leveraging the `anki-flashcard-mcp` server, you can use a large language model (LLM), such as Claude, to automatically generate flashcards and sync them with your Anki decks.

## Prerequisites ✅

Before you get started, please make sure you have the following installed:

* **Docker:** The containerization platform. 🐳
* **uv:** A fast Python package installer and bundler (recommended for development).
* **AnkiConnect Add-on:** This Anki add-on is required to allow the server to communicate with your Anki application. In Anki, go to `Tools > Add-ons > Get Add-ons...` and enter the code **2055492159**.
* **Anki Desktop:** The Anki application must be open and running for the server to work. 💡

## Development Setup (Optional) ⚙️

If you plan to develop or modify the server, you can set it up locally using `uv`.

1. **Initialize the project:**

```bash
uvx create-mcp-server anki-flashcard-mcp
cd anki-flashcard-mcp
```

2. **Install dependencies and run the server:**

```bash
uv sync --dev --all-extras
uv run my-server
```

## Running with Docker 📦

This is the recommended way to use the server.

1. **Build the Docker image:**

```bash
docker build -t anki-flashcard-mcp .
```

This command builds the Docker image and tags it as `anki-flashcard-mcp`.

2. **Test the server (optional):** You can test the container using the MCP inspector tool to ensure it's running correctly.

```bash
npx @modelcontextprotocol/inspector docker run -i --rm --init -e DOCKER_CONTAINER=true anki-flashcard-mcp
```

This command will run the inspector, which lets you test prompts and tools to verify the container's output.

## Using with the Claude App 🤖

Follow these steps to integrate the Dockerized server with the Claude desktop application.

1. **Enable Docker access for Claude:** Sometimes, Claude doesn't have the necessary shell environment variables to access Docker. Run the following command in your terminal to fix this:

```bash
launchctl setenv PATH "$PATH"
```

2. **Configure Claude Desktop:**
   * Open the Claude app and navigate to `Settings > Developer`.
   * Find the **Local MCP Servers** section and click `Edit Config`.
   * This will open `claude_desktop_config.json`. Add the following configuration to the JSON file:

```json
{
  "mcpServers": {
    "anki-flashcard-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "DOCKER_CONTAINER=true",
        "anki-flashcard-mcp"
      ]
    }
  }
}
```

3. **Troubleshooting - Wrapper Script (if direct config fails):** ⚠️ If the direct configuration doesn't work, you can use a shell script as a stable entry point.
   * Create a new script file, for example: `/Users/cademaxwell/.scripts/run-anki-docker.sh`

```bash
#!/bin/bash
exec /usr/local/bin/docker run -i --rm --init -e DOCKER_CONTAINER=true anki-flashcard-mcp
```

   * Make the script executable:

```bash
chmod +x ~/.scripts/run-anki-docker.sh
```

   * **Note:** Replace `/usr/local/bin/docker` with the actual path to your Docker executable (you can find this by running `which docker`).
   * Update the `claude_desktop_config.json` to point to the new script:

```json
{
  "mcpServers": {
    "anki-flashcard-mcp": {
      "command": "/Users/cademaxwell/.scripts/run-anki-docker.sh"
    }
  }
}
```

Your Dockerized MCP server is now ready to be used by Claude! Each time you open the Claude desktop app, a new Docker container will start for the `anki-flashcard-mcp` image.