# @lifeng688/anki-mcp

MCP stdio server for controlling local Anki via AnkiConnect. Enables LLMs (Claude, Cursor, Cline) to manage Anki decks and notes through a standardized tool interface.

**v0.2.0** — Controlled write operations with safe defaults (`dryRun`), tag management, and explicit sync confirmation.

## Quick Install

```bash
npm install @lifeng688/anki-mcp
```

Or try it instantly:

```bash
npx @lifeng688/anki-mcp
```

## Prerequisites

1. **Anki desktop** installed
2. **AnkiConnect** add-on (code `2055492159`) — install via *Tools → Add-ons → Get Add-ons*
3. **Node.js** >= 18.0.0

Verify AnkiConnect is running:

```bash
curl -X POST http://127.0.0.1:8765 \
  -H "Content-Type: application/json" \
  -d '{"action":"version","version":6}'
# Expected: {"result":6,"error":null}
```

## Core Features

- **Deck management** — List and create decks (including hierarchical `::` decks)
- **Note operations** — Add, search, update, delete, and inspect notes
- **Tag management** — Add and remove tags on notes by ID or search query
- **Batch operations** — Add multiple notes with per-item result tracking
- **Safe note deletion** — Delete notes with `dryRun` preview and explicit confirmation
- **Explicit sync** — Trigger AnkiCloud sync with confirmation guard
- **Controlled writes** — All mutation tools default to `dryRun=true`
- **Safety first** — `dryRun` support for batch writes, duplicate prevention, field validation
- **Unified responses** — Consistent success/error envelope across all tools
- **Security-focused** — Localhost only, no DB access, no card content logging

## Available Tools

| Tool | Description | Side Effects |
|---|---|---|
| `ping` | Server health check | None |
| `check_anki_connection` | Verify AnkiConnect reachable | None |
| `list_decks` | List all decks | None |
| `create_deck` | Create a new deck | Creates deck |
| `list_note_models` | List note models | None |
| `get_note_model_fields` | Get model fields | None |
| `add_note` | Add single note | Creates note |
| `add_notes` | Batch add notes | Creates notes |
| `search_notes` | Search notes | None |
| `get_notes_info` | Get note details | None |
| `update_note_fields` | Update note fields | Modifies note |
| `delete_notes` | Delete notes by ID or query | Deletes notes (requires confirm) |
| `add_tags` | Add tags to notes | Modifies note tags |
| `remove_tags` | Remove tags from notes | Modifies note tags |
| `sync_anki` | Trigger AnkiCloud sync | Triggers network sync (requires confirm) |

See [Tool Schema Reference](docs/tool-schema.md) for full input/output specs.

## MCP Client Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["$(npm root)/@lifeng688/anki-mcp/dist/index.js"]
    }
  }
}
```

With environment variables:

```json
{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["$(npm root)/@lifeng688/anki-mcp/dist/index.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://127.0.0.1:8765",
        "ANKI_CONNECT_VERSION": "6",
        "ANKI_DEFAULT_DECK": "Default::MCP",
        "ANKI_DEFAULT_MODEL": "Basic",
        "ANKI_LOG_LEVEL": "warn"
      }
    }
  }
}
```

> **Note:** Replace `$(npm root)/@lifeng688/anki-mcp/dist/index.js` with the actual resolved path. You can find it with:
> ```bash
> npm root -g
> # or
> npm root
> ```

### Cursor / Cline

Same JSON format — add to your MCP server configuration. Point `args` to the installed `dist/index.js` inside the `@lifeng688/anki-mcp` package directory.

### Global Install

```bash
npm install -g @lifeng688/anki-mcp
```

Then configure your client to point to:
```
<global-npm-root>/@lifeng688/anki-mcp/dist/index.js
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `ANKI_CONNECT_URL` | *(none)* | Full AnkiConnect HTTP endpoint (highest priority). Overrides HOST:PORT. |
| `ANKI_CONNECT_HOST` | `127.0.0.1` | Host part, used when `ANKI_CONNECT_URL` is not set. |
| `ANKI_CONNECT_PORT` | `8765` | Port part, used when `ANKI_CONNECT_URL` is not set. |
| `ANKI_CONNECT_VERSION` | `6` | AnkiConnect API version |
| `ANKI_CONNECT_KEY` | *(empty)* | AnkiConnect API key (if configured) |
| `ANKI_DEFAULT_DECK` | `Default` | Default deck for note operations |
| `ANKI_DEFAULT_MODEL` | `Basic` | Default note model |
| `ANKI_REQUEST_TIMEOUT_MS` | `10000` | HTTP request timeout in milliseconds |
| `ANKI_LOG_LEVEL` | `info` | Log verbosity: `error` / `warn` / `info` / `debug` |

**URL Resolution Priority:**

1. `ANKI_CONNECT_URL` — if set, used as-is (must point to localhost)
2. `ANKI_CONNECT_HOST` + `ANKI_CONNECT_PORT` — composed as `http://{HOST}:{PORT}`
3. `http://127.0.0.1:8765` — hardcoded default

## Security

- This server **only** connects to `http://127.0.0.1:8765` (localhost)
- It does **not** read/write Anki SQLite databases directly
- It does **not** upload any data externally
- `ANKI_CONNECT_KEY` is never logged
- **delete_notes** defaults to `dryRun=true`; real deletion requires `confirm="DELETE_NOTES"`
- **sync_anki** defaults to `dryRun=true`; real sync requires `confirm="SYNC_ANKI"`
- **add_tags** / **remove_tags** default to `dryRun=true`
- **import/export** are **not** in v0.2.0

## First-Time Setup

1. **Create a `Test::MCP` deck** before making real changes
2. Run `ping` and `check_anki_connection` to verify connectivity
3. Use `add_notes` with `dryRun: true` to preview before writing
4. **Before deleting notes**, always run `delete_notes` with `dryRun: true` first
5. **Before batch tag operations**, run `add_tags` / `remove_tags` with `dryRun: true` first
6. **sync_anki** requires explicit `confirm="SYNC_ANKI"` for real sync
7. Never expose port 8765 to the network

## Documentation

- [Installation & Configuration](docs/installation.md) — Full setup guide
- [Tool Schema Reference](docs/tool-schema.md) — All tools: input/output/examples/errors
- [Roadmap](docs/roadmap.md) — Feature progression plan (v0.1 → v0.6)
- [Security Guide](docs/security.md) — Boundaries, risks, safety policies
- [Conversation Quality Guide](docs/conversation-quality.md) — How LLMs should create cards
- [Testing Guide](docs/testing.md) — How to run the test suite

## License

MIT — See [LICENSE](LICENSE) for details.