anki-mcp-server 0.2.0__tar.gz

anki_mcp_server-0.2.0/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "anki-mcp-server",
+  "description": "Anki flashcards for Claude: create, import, edit, organize and add audio to your Anki cards.",
+  "owner": {
+    "name": "MeisamHakimi",
+    "url": "https://github.com/MeisamHakimi"
+  },
+  "plugins": [
+    {
+      "name": "anki-flashcards",
+      "source": "./plugins/anki-flashcards",
+      "description": "Create, import, search, edit and organize Anki flashcards, add pronunciation audio, and sync to your phone."
+    }
+  ]
+}

anki_mcp_server-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q
+      - run: python scripts/build_addon.py
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+      - uses: actions/setup-node@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        with:
+          node-version: "20"
+      - name: Build and validate the Claude Desktop extension
+        run: python scripts/build_mcpb.py
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+      - uses: actions/upload-artifact@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        with:
+          name: anki_mcp_bridge.ankiaddon
+          path: dist/anki_mcp_bridge.ankiaddon
+
+  installer:
+    # Runs the one-line installers in dry-run mode against this checkout. Runners have no Anki, so the wizard must
+    # stop at step 1 with install instructions, which proves uv + package install + wizard start work on each OS.
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: install.sh --dry-run
+        if: runner.os != 'Windows'
+        shell: bash
+        run: |
+          export ANKI_MCP_SOURCE="anki-mcp-server @ file://$GITHUB_WORKSPACE"
+          sh install.sh --dry-run --yes > out.txt 2>&1 || true
+          cat out.txt
+          grep -q "setup (dry run" out.txt
+          grep -qE "apps.ankiweb.net|would run: brew install" out.txt
+      - name: install.ps1 --dry-run
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $env:ANKI_MCP_SOURCE = "anki-mcp-server @ file:///$($env:GITHUB_WORKSPACE -replace '\\','/')"
+          ./install.ps1 --dry-run --yes *> out.txt
+          Get-Content out.txt
+          if (-not (Select-String -Path out.txt -Pattern "setup \(dry run" -Quiet)) { exit 1 }
+          if (-not (Select-String -Path out.txt -Pattern "apps.ankiweb.net" -Quiet)) { exit 1 }
+          $global:LASTEXITCODE = 0

anki_mcp_server-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: Release
+
+# Runs when a GitHub release is published (tag vX.Y.Z): publishes the package to PyPI with trusted publishing
+# (no API token stored anywhere) and attaches the Claude Desktop extension and the bridge add-on to the release.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # attach files to the release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - name: Check that the tag, package, plugin and launcher versions agree
+        run: |
+          v=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$v" = "$GITHUB_REF_NAME" || { echo "Tag $GITHUB_REF_NAME doesn't match version $v"; exit 1; }
+          grep -q "\"anki-mcp-server==$v\"" plugins/anki-flashcards/.mcp.json || { echo ".mcp.json isn't pinned to $v"; exit 1; }
+          grep -q "\"version\": \"$v\"" plugins/anki-flashcards/.claude-plugin/plugin.json || { echo "plugin.json version isn't $v"; exit 1; }
+      - run: python -m pip install build -e ".[dev]"
+      - run: python -m pytest -q
+      - run: python -m build
+      - run: python scripts/build_addon.py
+      - run: python scripts/build_mcpb.py
+      - name: Attach the desktop extension and the bridge add-on to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "$GITHUB_REF_NAME" dist/anki-mcp-server.mcpb dist/anki_mcp_bridge.ankiaddon --clobber
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/anki-mcp-server/
+    permissions:
+      id-token: write  # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

anki_mcp_server-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.DS_Store
+backups/
+build/

anki_mcp_server-0.2.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.2.0 (2026-10-16)
+
+- **Claude plugin** "Anki Flashcards (community)" in `plugins/anki-flashcards` (MCP server and a workflow skill), with a marketplace file so it can be added with `/plugin marketplace add MeisamHakimi/anki-mcp-server`
+- **Claude Desktop extension** (`anki-mcp-server.mcpb`) for one-click installs; Claude Desktop manages Python itself. Settings for read-only mode and deleting
+- Published on **PyPI** (`uvx anki-mcp-server`), released automatically by GitHub Actions with trusted publishing
+- Every tool now has a `title`; the audio tool is marked as reaching an outside service
+- `setup --skip-claude` for plugin users
+- Privacy policy (`PRIVACY.md`), security policy (`SECURITY.md`) and an icon
+
+## 0.1.0 (2026-10-07)
+
+First release.
+
+- Read: `anki_status`, `anki_find_notes`, `anki_list_tags`, `anki_open_browser`, `anki_tts_status`
+- Add: `anki_create_deck`, `anki_add_notes`, `anki_import_file` (TSV/CSV, header/columns mapping, tag rules, Anki plain-text exports), `anki_sync`
+- Audio: `anki_generate_audio` with built-in Google Translate voices (no add-on needed) or AwesomeTTS via the bridge add-on; only fills empty fields
+- Change and delete with preview → confirm tokens and automatic backups: `anki_update_notes`, `anki_move_notes`, `anki_rename_deck` (works without the bridge), `anki_rename_profile`, `anki_delete_notes`, `anki_delete_deck`
+- `anki_install_bridge` tool and `anki-mcp-server install-bridge` command to install the bundled bridge add-on
+- One-line installers (`install.sh`, `install.ps1`) and an `anki-mcp-server setup` wizard: installs uv, checks Anki (offers Homebrew/Flatpak install), installs and verifies AnkiConnect from AnkiWeb, optionally installs the bridge, restarts Anki, and configures Claude Desktop / Claude Code with backups; `--dry-run` supported
+- Installs from GitHub zip archives, so git isn't required
+- Localhost-only Anki connections, allowlisted AnkiConnect actions, read-only and no-delete modes, auto-launch of Anki with clear setup hints when Anki or AnkiConnect is missing

anki_mcp_server-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MeisamHakimi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anki_mcp_server-0.2.0/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.5
+Name: anki-mcp-server
+Version: 0.2.0
+Summary: MCP server for Anki (via AnkiConnect): add, import, search, edit and organize notes and decks from Claude or any MCP client.
+Project-URL: Homepage, https://github.com/MeisamHakimi/anki-mcp-server
+Project-URL: Issues, https://github.com/MeisamHakimi/anki-mcp-server/issues
+Author: MeisamHakimi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anki,ankiconnect,claude,flashcards,mcp,model-context-protocol,spaced-repetition
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Requires-Dist: gtts>=2.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# anki-mcp-server
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude (or any MCP client) work with your **Anki** flashcards. It can create decks, add notes, import TSV/CSV files, search, edit, move, rename and delete, **add pronunciation audio**, and sync to AnkiWeb so changes reach AnkiDroid / AnkiMobile.
+
+> "Create a deck Spanish::Verbs and add these 10 verbs with example sentences."
+> "Import `~/Downloads/spanish.csv` into my Spanish deck. Do a dry run first."
+> "Add Spanish pronunciation audio to the notes I added today, then sync."
+> "Find every card tagged `verbs` that has no example sentence."
+> "Move all notes tagged `grammar` into Spanish::Grammar."
+
+It works on **macOS, Windows and Linux**, with Anki Desktop and the free [AnkiConnect](https://ankiweb.net/shared/info/2055492159) add-on.
+
+---
+
+## Install
+
+### 1. Install Anki Desktop (once)
+
+Download it from **<https://apps.ankiweb.net>**, install it, and **open it once**: its first window asks for a language and creates your profile.
+- **macOS:** open the `.dmg` and drag Anki to Applications. With Homebrew: `brew install --cask anki`.
+- **Windows:** run the installer (`anki-…-windows.exe`).
+- **Linux:** use the official package from the download page, or Flatpak: `flatpak install flathub net.ankiweb.Anki`.
+
+Anki 23.10 or newer is required.
+
+*Phone:* to get your cards on your phone, create a free [AnkiWeb](https://ankiweb.net) account, click **Sync** in Anki, and sign in to AnkiDroid (Android) or AnkiMobile (iPhone) with the same account.
+
+### 2. Connect it to Claude: pick one
+
+| You use | Easiest option |
+|---|---|
+| **Claude Desktop** (chat) | [A. Desktop extension](#a-claude-desktop-extension-one-click): one click, nothing else to install |
+| **Claude Code** or **Cowork** | [B. Plugin](#b-claude-code--cowork-plugin) |
+| Not sure, or you want everything set up for you | [C. One-line installer](#c-one-line-installer-sets-up-everything) |
+
+Use only one of A and C for Claude Desktop; otherwise Claude sees the tools twice.
+
+#### A. Claude Desktop extension (one click)
+
+1. **AnkiConnect:** in Anki choose **Tools → Add-ons → Get Add-ons…**, enter **`2055492159`**, click OK, then **restart Anki**.
+2. Download **[anki-mcp-server.mcpb](https://github.com/MeisamHakimi/anki-mcp-server/releases/latest/download/anki-mcp-server.mcpb)** from the latest release.
+3. **Double-click** it, or in Claude Desktop go to **Settings → Extensions → Advanced settings → Install Extension…**, then click **Install**.
+
+Claude Desktop takes care of Python and everything else. In the extension's settings you can turn on **read-only mode** or turn off deleting.
+
+#### B. Claude Code / Cowork plugin
+
+- **Claude Code:** run these two commands in a session:
+
+  ```text
+  /plugin marketplace add MeisamHakimi/anki-mcp-server
+  /plugin install anki-flashcards@anki-mcp-server
+  ```
+
+- **Claude app (Cowork):** go to **Customize → Plugins → Add → Add marketplace**, enter `MeisamHakimi/anki-mcp-server`, then add **Anki Flashcards (community)**.
+
+The plugin adds the server and a skill that teaches Claude good Anki habits: dry runs first, and your approval before any change. It needs [uv](https://docs.astral.sh/uv/getting-started/installation/) and AnkiConnect. After installing uv, run `uvx anki-mcp-server setup --skip-claude` to check Anki and install AnkiConnect. The server runs on your computer, so the plugin works in **Claude Code and in Cowork sessions on your computer**, not in regular claude.ai chat (use option A for that).
+
+#### C. One-line installer (sets up everything)
+
+**macOS / Linux** (Terminal):
+
+```bash
+curl -LsSf https://raw.githubusercontent.com/MeisamHakimi/anki-mcp-server/main/install.sh | sh
+```
+
+**Windows** (PowerShell):
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/MeisamHakimi/anki-mcp-server/main/install.ps1 | iex"
+```
+
+The installer:
+1. installs [uv](https://docs.astral.sh/uv/) if it's missing. uv brings its own Python, so you don't need Python or git.
+2. starts the setup wizard, which **asks before every change**:
+   - checks that Anki is installed (and offers to install it with Homebrew/Flatpak, or opens the download page),
+   - installs the **AnkiConnect** add-on from AnkiWeb (the same download Anki's *Get Add-ons* uses, verified before installing),
+   - optionally installs the **Anki MCP Bridge** add-on (recommended if you use AwesomeTTS),
+   - restarts Anki and checks the connection,
+   - adds the server to **Claude Desktop** (backing up your config; an existing `anki` entry is never replaced without asking) and to **Claude Code** if it's installed.
+
+Add `--dry-run` to see what it would do without changing anything (`… | sh -s -- --dry-run`). To read the scripts first, see [install.sh](install.sh) and [install.ps1](install.ps1).
+
+### 3. Try it
+
+Restart Claude Desktop **completely** (⌘Q on Mac, File → Exit on Windows) after options A or C. Then say **"Check my Anki status."**
+
+You don't need to open Anki first: if it isn't running, the server starts it in the background. Claude asks permission the first time it uses each tool.
+
+### Manual setup
+
+1. **AnkiConnect:** in Anki choose **Tools → Add-ons → Get Add-ons…**, enter **`2055492159`**, click OK, then restart Anki.
+2. **uv:** run `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows). Then find the **full path** of uvx with `which uvx` (macOS/Linux) or `where uvx` (Windows).
+3. **Claude Desktop:** go to Settings → Developer → Edit Config, add the following inside the top-level `{ }`, save, and fully restart Claude. Use the full uvx path: desktop apps often can't see your terminal's PATH.
+
+   ```json
+   "mcpServers": {
+     "anki": {
+       "command": "/Users/<you>/.local/bin/uvx",
+       "args": ["anki-mcp-server"]
+     }
+   }
+   ```
+
+   If `"mcpServers"` already exists, add just the `"anki": {…}` part inside it.
+4. **Claude Code:**
+
+   ```bash
+   claude mcp add anki --scope user -- uvx anki-mcp-server
+   ```
+
+5. **Other MCP clients:** run `uvx anki-mcp-server` (or `pip install anki-mcp-server`, then run `anki-mcp-server`) as a stdio server.
+
+**macOS tip:** if Anki responds slowly while it's in the background, run this once and restart Anki:
+
+```bash
+defaults write net.ankiweb.dtop NSAppSleepDisabled -bool true
+```
+
+### Updating
+
+- **Desktop extension:** download the newer `.mcpb` from Releases and install it again.
+- **Plugin:** updates arrive automatically from the marketplace.
+- **Installer:** run it again, then restart Claude.
+
+---
+
+## Pronunciation audio (text-to-speech)
+
+Audio works **out of the box**:
+
+> "Add audio of the Word field into the Audio field for deck:"English" notes."
+> "Add Spanish audio (lang es) of the Front field into the Back field for notes added today."
+
+- **Built-in engine (default):** free Google Translate voices in 60+ languages (`lang`: `en`, `es`, `fr`, `de`, `ja`, `zh-CN`, …) and English accents (`accent`: `com` US, `co.uk`, `com.au`, `ca`, `co.in`). No add-on or API key is needed. It needs internet, and the text being spoken is sent to Google.
+- **AwesomeTTS:** if you use the [AwesomeTTS](https://ankiweb.net/shared/info/1436550454) add-on and install the bridge add-on (below), audio uses your AwesomeTTS voice and presets automatically.
+- **Nothing is overwritten:** only notes whose audio field is empty get audio. Use `dry_run` to preview.
+
+Audio is stored as `[sound:…]` in the field you choose. If your note type has no audio field, use an existing one (e.g. `Back`), or add a field in Anki via Tools → Manage Note Types → Fields.
+
+## Optional: the Anki MCP Bridge add-on
+
+Everything works without it. The bridge adds three things AnkiConnect can't do:
+- Rename your **Anki profile** (e.g. "User 1" → your name)
+- **Exact deck renames**, which keep the deck description and allow capitalization-only changes. Without the bridge, renames move the cards to a newly named deck, which keeps the cards, review history and options.
+- Use your **AwesomeTTS** voice
+
+**Install:** say yes when the installer offers it, or ask Claude *"Install the Anki MCP bridge"*. Then restart Anki.
+
+It listens on `127.0.0.1:8766` only, refuses requests from web browsers, and never returns AwesomeTTS settings or API keys. AwesomeTTS support relies on AwesomeTTS internals (tested with 1.89.4), so an AwesomeTTS update could break only that feature.
+
+---
+
+## Safety
+
+Your collection is personal data you've built over years, so this server is cautious by default:
+
+- **Local connections only.** It uses the stdio transport (no network listener) and only talks to Anki on `127.0.0.1`; other URLs are rejected. The one exception is built-in TTS, which sends the spoken text to Google (see [Privacy Policy](#privacy-policy)).
+- **Adding never overwrites.** Notes are added with `allowDuplicate=false`; duplicates are reported back as skipped. `dry_run` previews adds, imports and audio.
+- **Changes and deletions are two-step.** A tool that edits, moves, renames or deletes first returns a **preview** and a `confirm_token`, without changing anything. The change only runs when the tool is called again with that token. The token is rejected if the arguments differ, if the notes changed since the preview, or if the server restarted. The server tells the model to get your explicit approval first.
+- **Backups before every change** go to `~/.anki-mcp-server/backups/`: affected notes as JSON, and deleted decks as an `.apkg` with review history (restore it via Anki → File → Import). AnkiConnect edits bypass Anki's undo, so these backups are your undo. Anki's own automatic backups (File → Switch Profile → Open Backup) are another safety net.
+- **Allowlisted actions.** Only the AnkiConnect actions this server needs are used. Note-type, template and deck-option editing are never exposed.
+- **Modes.** `ANKI_MCP_READ_ONLY=1` exposes only read tools. `ANKI_MCP_ALLOW_DELETE=0` hides the delete tools.
+- **Tool annotations.** Every tool is marked read-only or destructive, so MCP clients can ask for confirmation appropriately.
+
+## Tools
+
+| Tool | Kind | What it does |
+|---|---|---|
+| `anki_status` | read | AnkiConnect version, profile, decks, note types and their fields, available features |
+| `anki_find_notes` | read | [Anki search syntax](https://docs.ankiweb.net/searching.html) → notes with fields, tags and decks |
+| `anki_list_tags` | read | All tags |
+| `anki_open_browser` | read | Opens Anki's Browse window filtered by a search |
+| `anki_tts_status` | read | Available audio engines, languages and AwesomeTTS presets |
+| `anki_create_deck` | add | Creates a deck (`Parent::Child` for subdecks); a no-op if it exists |
+| `anki_add_notes` | add | Adds notes; duplicates skipped; `dry_run` |
+| `anki_import_file` | add | Imports `.txt/.tsv/.csv`: header or `columns` mapping, a `tags` column, `tag_rules`, Anki plain-text exports, `dry_run` |
+| `anki_generate_audio` | add | Text-to-speech into empty audio fields (Google built-in or AwesomeTTS) |
+| `anki_sync` | add | Syncs with AnkiWeb |
+| `anki_update_notes` | change | Edits fields and tags (preview → confirm, backup) |
+| `anki_move_notes` | change | Moves notes to another deck (preview → confirm, backup) |
+| `anki_rename_deck` | change | Renames a deck and its subdecks (preview → confirm) |
+| `anki_rename_profile` | change | Renames the Anki profile (preview → confirm; bridge) |
+| `anki_install_bridge` | change | Installs or updates the bridge add-on (preview → confirm) |
+| `anki_delete_notes` | delete | Deletes notes (preview → confirm, JSON backup) |
+| `anki_delete_deck` | delete | Deletes a deck and its cards (preview → confirm, `.apkg` + JSON backup) |
+
+### Note types and field names
+
+You can use friendly field names. Matching is case-insensitive, and a unique prefix works: `"example"` maps to a field called `Example sentence`. If you don't pass `model`, adds and imports use `ANKI_DEFAULT_MODEL`, else the note type most used in the target deck, else Anki's standard `Basic` (Front/Back).
+
+### Importing files
+
+```text
+word	meaning	example
+resilient	able to recover quickly	She is remarkably resilient.
+GRAMMAR NOTE: present perfect	have/has + past participle	I have lived here for years.
+```
+
+> "Import `~/vocab.txt` into `English::Vocabulary`. Tag rows whose word starts with `GRAMMAR NOTE:` as `grammar` and everything else as `vocab`."
+
+This becomes:
+
+```json
+{"path": "~/vocab.txt", "deck": "English::Vocabulary",
+ "tag_rules": [{"field": "Word", "starts_with": "GRAMMAR NOTE:", "tag": "grammar"}],
+ "default_tag": "vocab", "dry_run": true}
+```
+
+- **Delimiter:** tab, comma, semicolon or pipe, auto-detected. Tab-separated files are read literally; other delimiters follow CSV quoting rules. Files must be UTF-8.
+- **Columns:** taken from a header row if there is one (auto-detected when it matches field names), else from `columns`, else in the note type's field order. Use `""` to skip a column and `"tags"` for a space-separated tags column.
+- **Anki exports:** "Notes in Plain Text" exports work, including their `#separator:` and `#columns:` lines.
+- **Tag rules:** each rule needs `field`, `tag`, and one of `starts_with`, `contains` or `regex`. They're case-insensitive unless you set `"case_sensitive": true`.
+
+## Configuration (optional)
+
+Set these in the `env` block of your MCP config.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ANKI_CONNECT_URL` | `http://127.0.0.1:8765` | AnkiConnect address (must be localhost) |
+| `ANKI_CONNECT_API_KEY` | – | Set this if you configured `apiKey` in AnkiConnect |
+| `ANKI_MCP_BRIDGE_URL` | `http://127.0.0.1:8766` | Bridge add-on address (must be localhost) |
+| `ANKI_AUTO_LAUNCH` | `1` | Start Anki if it isn't running |
+| `ANKI_LAUNCH_COMMAND` | per OS | Custom command to start Anki, e.g. `flatpak run net.ankiweb.Anki` |
+| `ANKI_BASE` | per OS | Anki's data folder, used to install the bridge (Anki: Tools → Add-ons → View Files, one level up) |
+| `ANKI_MCP_BACKUP_DIR` | `~/.anki-mcp-server/backups` | Where backups go |
+| `ANKI_DEFAULT_MODEL` | – | Default note type for adds/imports |
+| `ANKI_MCP_READ_ONLY` | `0` | `1` = read tools only |
+| `ANKI_MCP_ALLOW_DELETE` | `1` | `0` = hide the delete tools |
+
+```json
+"anki": {
+  "command": "/Users/<you>/.local/bin/uvx",
+  "args": ["anki-mcp-server"],
+  "env": { "ANKI_MCP_ALLOW_DELETE": "0" }
+}
+```
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| Claude doesn't list the **anki** tools | Fully quit and reopen Claude. Run the installer again (it fixes the config), or check that the config uses the **full path** to `uvx`. Claude Desktop → Settings → Developer shows the server's error. |
+| "Can't connect to AnkiConnect" | Run the installer again, or install AnkiConnect manually and restart Anki. To check, run `curl -s localhost:8765 -X POST -d '{"action":"version","version":6}'`; it should print `{"result": 6, ...}`. |
+| "Anki isn't installed / couldn't be found" | Install Anki (step 1) and open it once. For a non-standard install, set `ANKI_LAUNCH_COMMAND`. |
+| "Started Anki, but AnkiConnect didn't answer" | Anki is waiting at the profile picker or a dialog; check its window. Otherwise AnkiConnect isn't installed. |
+| Slow or timing out on macOS | Run the App Nap command from *Manual setup*, then restart Anki. |
+| Audio fails | Built-in audio needs internet. If several requests fail, Google may be rate-limiting; try again later or with a smaller `limit`. |
+| An edit shows `not_applied` | The note was open in Anki's editor or Browse window. Close it and retry. |
+| "needs the Anki MCP Bridge add-on" | Ask Claude to install the bridge, then restart Anki. |
+| Restoring something | Decks: import the `.apkg` from the backup folder (File → Import). Notes: the JSON backups contain every field and tag. Whole collection: Anki's File → Switch Profile → Open Backup. |
+
+## Development
+
+```bash
+git clone https://github.com/MeisamHakimi/anki-mcp-server && cd anki-mcp-server
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest                 # tests use fake AnkiConnect and bridge servers; Anki isn't needed
+python scripts/build_addon.py    # builds dist/anki_mcp_bridge.ankiaddon
+python scripts/build_mcpb.py     # builds dist/anki-mcp-server.mcpb (needs Node.js)
+claude plugin validate ./plugins/anki-flashcards   # checks the Claude plugin
+.venv/bin/anki-mcp-server setup --dry-run   # try the setup wizard without changing anything
+npx @modelcontextprotocol/inspector .venv/bin/anki-mcp-server   # try the tools interactively
+```
+
+## Privacy Policy
+
+anki-mcp-server runs entirely on your computer. The author collects no data and runs no servers, and there is no telemetry.
+- **Your notes** are read and changed locally through Anki/AnkiConnect on `127.0.0.1`. Tool results go to the AI app you use (e.g. Claude) under that app's privacy policy.
+- **Third parties, only when you use these features:**
+  - **Google** receives the text being spoken by the built-in text-to-speech.
+  - **AnkiWeb** receives your collection when you sync, through Anki itself.
+  - **AnkiWeb, PyPI, GitHub and astral.sh** serve the downloads during installation; these requests contain no personal data.
+- **Retention:** backups stay in `~/.anki-mcp-server/backups/` on your computer until you delete them. Nothing is kept by the author.
+- **Contact:** [GitHub issues](https://github.com/MeisamHakimi/anki-mcp-server/issues), or private reports through [security advisories](https://github.com/MeisamHakimi/anki-mcp-server/security/advisories/new).
+
+Full policy: [PRIVACY.md](PRIVACY.md). Security policy: [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT. This is an unofficial community project, not affiliated with or endorsed by Anki/Ankitects, AnkiConnect, AwesomeTTS, Google or Anthropic.

anki_mcp_server-0.2.0/PRIVACY.md

@@ -0,0 +1,40 @@
+# Privacy Policy
+
+*Last updated: 2026-10-16. Applies to anki-mcp-server, its Claude plugin ("Anki Flashcards"), its Claude Desktop extension, and the Anki MCP Bridge add-on.*
+
+anki-mcp-server is free, open-source software that runs **on your own computer**. The author does not operate any server for it and does not collect, receive, store or sell any of your data. There is no analytics, telemetry or tracking.
+
+## What data it handles and where it goes
+
+| Data | Where it goes | When |
+|---|---|---|
+| Your Anki notes, decks, tags and profile name | Read and changed **locally** through Anki and the AnkiConnect add-on on `127.0.0.1`. Tool results are returned to the AI app you use (e.g. Claude), which processes them under **that** app's privacy policy (for Claude: <https://www.anthropic.com/legal/privacy>) | Whenever you or the AI use a tool |
+| Text you turn into audio with the **built-in** text-to-speech engine | Sent to **Google's** Translate text-to-speech service to create the MP3 file ([Google Privacy Policy](https://policies.google.com/privacy)) | Only when `anki_generate_audio` runs with the `google` engine (the default when AwesomeTTS isn't installed) |
+| Text you turn into audio with **AwesomeTTS** | Handled by the AwesomeTTS add-on and the voice service *you* configured in it | Only when `anki_generate_audio` uses the `awesometts` engine |
+| Your whole collection, when you sync | Sent by Anki itself to **AnkiWeb** ([AnkiWeb privacy](https://ankiweb.net/account/privacy)) | Only when `anki_sync` runs or you sync in Anki |
+| Nothing personal: software downloads | The installer and setup download uv (astral.sh), this package (PyPI / GitHub) and, if you agree, the AnkiConnect add-on (ankiweb.net). These requests contain no personal data | Only during installation / setup |
+
+## Storage and retention
+
+- **Backups:** before editing, moving, renaming or deleting, the affected notes are saved as JSON (and deleted decks as `.apkg`) in `~/.anki-mcp-server/backups/` (or `ANKI_MCP_BACKUP_DIR`). They stay on your computer until **you** delete them.
+- **Audio files** are stored in your Anki collection's media folder like any other Anki media.
+- **Configuration:** setup writes the server entry into your Claude Desktop configuration (after asking, with a backup) and installs add-ons into Anki's add-ons folder.
+- Nothing else is stored, and nothing is kept by the author.
+
+## Third-party sharing
+
+The author shares no data with anyone. Data only reaches the third parties listed above (Google, AnkiWeb, your AI app, your AwesomeTTS voice service), and only through the actions described there.
+
+## Your choices
+
+- Use `ANKI_MCP_READ_ONLY=1` (read-only) or `ANKI_MCP_ALLOW_DELETE=0` (no delete tools).
+- Avoid sending text to Google by using AwesomeTTS with a local voice, or by not using the audio tool.
+- Uninstall at any time: remove the server from your Claude configuration, delete `~/.anki-mcp-server/`, and remove the add-ons in Anki (Tools → Add-ons).
+
+## Children
+
+The software is not directed at children under 13 and collects no personal information from anyone.
+
+## Changes and contact
+
+Changes to this policy are published in this file with a new date. Questions or requests: open an issue at <https://github.com/MeisamHakimi/anki-mcp-server/issues>, or report privately via <https://github.com/MeisamHakimi/anki-mcp-server/security/advisories/new>.