# Anki MCP Server

[npm](https://www.npmjs.com/package/stefanwille-anki-mcp-server)

A Model Context Protocol (MCP) server for managing [Anki](https://apps.ankiweb.net/) flashcards. Connects to [AnkiConnect](https://foosoft.net/projects/anki-connect/) to enable AI assistants to create, read, and update flashcards.

## Prerequisites

- [Anki](https://apps.ankiweb.net/) with [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on installed
- Node.js 24+ ([Download](https://nodejs.org/en/download))
- Anki running, with AnkiConnect on `http://127.0.0.1:8765` (default)

## Installation in Claude Desktop

- Open Claude Desktop
- Go to: "Claude" / "Settings..."
- Tab "Developer"
- Click "Edit Config"

Edit your Claude Desktop config (`claude_desktop_config.json`), and add:

```json
{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["-y", "stefanwille-anki-mcp-server@latest"]
    }
  }
}
```

Restart Claude Desktop to activate.

## Troubleshooting

### "Failed to spawn process" / "command not found: npx" on macOS

Claude Desktop launches with a restricted `PATH` that doesn't include Node.js when installed via version managers like **Volta** or **nvm**. You'll see errors like:

```
Failed to spawn process: No such file or directory
```

or

```
node: command not found
```

**Fix:** Use the full path to `npx` and add the Node.js bin directory explicitly via `env`:

```json
{
  "mcpServers": {
    "anki": {
      "command": "/Users/YOUR_USERNAME/.volta/bin/npx",
      "args": ["-y", "stefanwille-anki-mcp-server@latest"],
      "env": {
        "PATH": "/Users/YOUR_USERNAME/.volta/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}
```

Replace `YOUR_USERNAME` with your macOS username and adjust the path if you use **nvm** (`~/.nvm/versions/node/vX.X.X/bin/`) or another version manager.

Find your actual `npx` path by running in a terminal:

```bash
which npx
```

## Example Prompts

- "What decks do I have in Anki?"
- "Show the cards in my Spanish vocabulary deck"
- "Check all cards in deck 'Italiano::Capitulo 3' for grammatical errors and correct them"
- "Create a card in my Italian deck with 'ciao' on the front and 'hello' on the back"
- "Extract the vocabulary from the photo and add it to my Italian deck with Italian on the front and German on the back: ..."
- "Create a new deck called 'Physics::Quantum Mechanics'"
- "Rename my 'Math' deck to 'Mathematics'"
- "Give me an exercise that requires me to use the Italian words in the deck 'Italienisch::Capitulo 6::Italienisch 38 - 2025-08-01'"

## Tools


| Tool           | Description                                  |
| -------------- | -------------------------------------------- |
| `get_decks`    | Get all deck names from Anki                 |
| `create_deck`  | Create a new deck                            |
| `delete_deck`  | Delete a deck and all its cards (including sub-decks) |
| `list_cards`   | List cards in a deck with front/back content |
| `create_cards` | Create one or more basic cards in a deck     |
| `update_card`  | Update an existing card's content            |
| `rename_deck`  | Rename a deck                                |


## Development

### Prerequisites

- Node.js 24+
- pnpm ([Installation](https://pnpm.io/installation))

### Build from Source

```bash
git clone https://github.com/stefanwille/anki-mcp-server.git
cd anki-mcp-server
pnpm install
pnpm build
```

### Watch Mode

```bash
pnpm watch
```

Rebuilds automatically on file changes.

### Install Locally

Update Claude Desktop config to point directly to the built file:

```json
{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["/absolute/path/to/anki-mcp-server/dist/index.js"]
    }
  }
}
```

Replace `/absolute/path/to/anki-mcp-server` with your actual clone location.

### Publish to npm

Create a GitHub release to trigger the npm publish workflow:

```bash
pnpm login 
# If pnpm login produces a 404 page, try pnpm login again
pnpm version patch  # or minor, major
git push && git push --tags
gh release create v$(node -p "require('./package.json').version") --generate-notes
```

This triggers the GitHub Actions workflow that publishes to npm automatically using [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC), not access tokens.

## License

MIT