Vionwinnie Jap Vocab Anki MCP Server

🚀 Japanese Anki MCP Server

A Model Context Protocol server implementation for programmatically interacting with Anki decks via a standard interface. This server is specifically designed to support Japanese language learning and allows language models to interact with Anki through a unified interface.

🚀 Quick Start

This server enables seamless interaction with Anki decks, especially tailored for Japanese language learning. It offers a range of features to enhance vocabulary learning and review processes.

✨ Features

• List available decks.
• View cards within a deck.
• Add new cards.
• Review cards using spaced repetition.
• Import Japanese vocabulary along with their pronunciations and meanings.
• Add example sentences to Japanese vocabulary cards.
• Track review history and learning progress.

💻 Usage Examples

End-to-End Example: Enhancing Japanese Vocabulary Learning with Claude

The following is a complete process example demonstrating how to leverage Claude to enhance the learning of Japanese vocabulary cards.

Step 1: Generate Fill-in-the-Blank Exercises

First, request Claude to create exercises using the study_japanese_vocab_prompt:

Claude will create context sentences with blanks from the recently reviewed vocabulary to test the understanding of the words.

Step 2: Convert to Example Sentences

Next, use the vocab_sentences_json_prompt to convert these sentences into a structured format:

Claude will convert the sentences into a JSON dictionary, where each Japanese vocabulary maps to its corresponding example sentence.

Step 3: Update Anki Cards

Finally, use the update_notes_with_sentences tool to add these example sentences to Anki cards:

The example sentences will be added to the "Pronunciation" field of each vocabulary card, providing more context for learning.

Results in Anki

After the update, your cards will contain new example sentences:

This process helps you:

1. Practice vocabulary in context through fill-in-the-blank exercises.
2. Add natural example sentences to cards.
3. Build a more comprehensive understanding of how each word is used.

📦 Installation

1. Clone this repository:

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

💻 Usage

1. Ensure Anki is not running (to avoid database locking).
2. Set the Anki collection path (optional):

export ANKI_COLLECTION_PATH="/path/to/your/collection.anki2"

3. Run the server:

python -m anki_mcp.server

📚 Documentation

Available Resources

• anki://decks - List all available Anki decks.
• anki://deck/{deck_name}/cards - View all cards in a specific deck.
• anki://recent/reviewed - View cards reviewed in the past 24 hours.
• anki://recent/learned - View cards learned (graduated from new cards) in the past 24 hours.

Available Tools

Basic Card Management

• add_card(deck_name: str, front: str, back: str) - Add a new card to a deck.
• review_card(card_id: int, ease: int) - Review a card with a specific difficulty level (1 - 4).
• get_card_history(card_id: int) - Get the detailed review history of a specific card.

Japanese Vocabulary Features

• import_japanese_vocab(csv_path: str, deck_name: str, tags: str = None) - Import Japanese vocabulary from a CSV file.
• update_notes_with_sentences(vocab_sentences: Dict[str, List[str]], deck_name: str = "Try! N3 Vocab") - Add example sentences to vocabulary cards.

View Review History

• get_review_history() - Get the review history records of all users.
• get_deck_stats(deck_name: str) - Get the statistics of a specific deck.
• export_cards(deck_name: str, filename: str) - Export a deck as a CSV file.

Preset Prompts

Generate Fill-in-the-Blank Exercises

# Fill-in-the-Blank Exercise Prompt
response = client.chat.completions.create(
    model="Claude-2",
    messages=[
        {
            "role": "system",
            "content": """As a Japanese teacher, create fill-in-the-blank exercises for students. Based on the provided vocabulary, generate appropriate sentences and fill the target vocabulary with blanks _ _ _. Keep the sentences concise and suitable for beginner learners. Output format: Each sentence should be on a new line and returned in JSON format."""
        },
        {
            "role": "user",
            "content": "Japanese Vocabulary: 忍者, 学校, 公园"
        }
    ],
    temperature=0.7,
)

Convert to Structured Data

# Structured Conversion Prompt
response = client.chat.completions.create(
    model="Claude-2",
    messages=[
        {
            "role": "system",
            "content": """Convert the incomplete sentence JSON into structured Japanese example sentences. Output format: Each sentence should include the original sentence, the blank form, and the correct fill."""
        },
        {
            "role": "user",
            "content": "[[\"Original Sentence\",\"_ _ _, あなたはプログラマーです。\"],[\"Blank Form\",\"_ _ _ , あなたはプログラマーです。\"]]"
        }
    ],
    temperature=0.7,
)

Japanese Note Type Requirements

• Expression: Japanese vocabulary or phrases.
• Meaning: Corresponding English translation and pronunciation (e.g., "ninja" /ˈninjə/).
• Pronunciation: Hiragana, including example sentences and blank forms.

Example:

{
  "expression": "忍者",
  "reading": "にんじゃ",
  "meaning": "ninja",
  "sentences": [
    {
      "original": "忍者は公園で稽古をしていた。",
      "blank": "_ _ _ は公園でけいじゅうをしていた。",
      "correct": "忍者"
    }
  ]
}

This project provides a powerful tool for Japanese learners, significantly enhancing the effectiveness of vocabulary learning through integration with Anki.