jap-vocab-anki

This MCP server provides a Python-based interface to interact with Anki decks for Japanese vocabulary learning. It exposes resources to list decks, view deck cards, and manage cards, along with specialized Japanese vocabulary features such as importing vocabulary with readings, adding sample sentences, and reviewing cards. You can query available decks at anki://decks, inspect cards in a deck with anki://deck/{deck_name}/cards, and review or track progress via the included review endpoints. The included tools let you add new cards, review cards with a chosen ease, import Japanese vocabulary from CSV, and attach example sentences to existing vocabulary notes to provide context.

To use the server, run the Python module as documented, then invoke the supported functions through your LLM or client code. Basic operations include adding a card to a deck, updating notes with sentences, and managing review history. For Japanese vocabulary workflows, you can import a CSV of vocab terms with readings and meanings, then enrich those cards by appending natural language sentences to the Reading field. The server also provides prompts to help generate study exercises and convert them into structured JSON suitable for subsequent processing.

Prerequisites:

• Python 3.8+ installed
• Git
• Optional: Anki installed if you plan to use the actual Anki database interactions locally

Installation steps:

1. Clone the repository

git clone https://github.com/vionwinnie/jap-vocab-anki-mcp-server.git
cd jap-vocab-anki-mcp-server

2. (Optional) Create and activate a virtual environment

python -m venv venv
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt  # if a requirements file exists

4. Prepare environment (optional)

• Set ANKI_COLLECTION_PATH to the path of your Anki collection (e.g., /path/to/collection.anki2) if you want to point the server to a specific collection.

export ANKI_COLLECTION_PATH="/path/to/your/collection.anki2"
# Windows PowerShell
$env:ANKI_COLLECTION_PATH = "/path/to/your/collection.anki2"

5. Run the MCP server

python -m anki_mcp.server

6. Verify the server is listening (default behavior)

• Use curl or your client to call the supported endpoints and tools described in the README.

Tips and notes:

• If you encounter database-locking issues with Anki, ensure Anki is fully closed before starting the MCP server.
• The server expects a note type named "Japanese (recognition)" with fields: Expression (Japanese word), Meaning (English meaning), and Reading (with furigana and sample sentences). If your collection uses a different note type, you may need to adapt the integration.
• The optional ANKI_COLLECTION_PATH environment variable lets you point the server directly to a specific Anki collection. Without it, the server will attempt to operate on the default local collection.
• Available resources include listing decks, cards within decks, and recent review data. Available tools include adding cards, reviewing cards with an ease factor, importing Japanese vocabulary from CSV, and updating notes with sample sentences.
• The server exposes prompts such as study_japanese_vocab_prompt() and vocab_sentences_json_prompt() to assist with generating study content and converting it into JSON-friendly formats.