Content
# Tool List
A smart Anki vocabulary manager based on MCP (Model Context Protocol), supporting automatic generation of pronunciation, intelligent search, and statistical analysis.
## Features
- Intelligent Vocabulary Management
- Batch add words and individual add
- Automatically generate pronunciation for words, definitions, and examples (OpenAI TTS)
- Support for tag system and note function
- CSV format storage, support for version control, prevent word loss
- Advanced Search and Analysis
- Multi-dimensional sorting: due date, recent review, difficulty, etc.
- Intelligent search: support for fuzzy matching of words and definitions
- Detailed statistics: review times, accuracy, familiarity, etc.
- Automation Tools
- Fully automated Anki card creation
- Intelligent audio caching system
- Detailed log recording
## Tool Commands
### add-words-batch
Add words to vocabulary list and create Anki cards (support single and batch operations)
Input:
- words: word array, each containing:
- word: word (only English)
- definition: definition (only English)
- example: example sentence (optional, only English)
- notes: notes (optional, only English)
- tags: tag array (optional, only support letters, numbers, hyphens, and underscores)
### list-words
List words in Anki, support multiple sorting methods:
- due: sort by due date (unfamiliar words first)
- recent: sort by review frequency (recently reviewed first)
- difficulty: sort by accuracy (most challenging first)
- added: sort by creation time (newly added first)
- lapses: sort by forgotten times (most forgotten first)
### search-words
Search words and definitions in Anki deck
Input:
- query: search keyword
- limit: return result number (1-50, default 20)
## Installation Requirements
1. Node.js (v16+)
2. Anki
3. AnkiConnect plugin (plugin code: 2055492159)
4. OpenAI API key
### AnkiConnect Plugin Installation
1. Open Anki
2. Click top menu Tools -> Add-ons
3. Click "Get Add-ons..." button
4. Input plugin code: `2055492159`
5. Click OK to install
6. Restart Anki to take effect
7. Verification:
- Ensure Anki is running
- Access `http://localhost:8765` in browser
- If see blank page or JSON response, plugin installation successful
## Quick Start
1. Clone repository:
```bash
git clone <repository-url>
cd anki-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build project:
```bash
npm run build
```
## MCP Configuration
Configure in Claude Desktop (edit `~/.config/claude-mcp/config.json`):
```json
{
"servers": {
"anki-mcp": {
"command": "node",
"args": ["/path-of-project/build/index.js"],
"env": {
"OPENAI_API_KEY": "Your OpenAI API key",
"OPENAI_API_BASE": "Optional API base URL",
"ANKI_DECK_NAME": "Your Anki deck name",
"ANKI_MODEL_NAME": "Your card template name",
"ANKI_CONNECT_URL": "http://localhost:8765"
}
}
}
}
```
## Environment Variables
| Variable Name | Description | Default Value |
|--------------|-------------|---------------|
| OPENAI_API_KEY | OpenAI API key | Required |
| OPENAI_API_BASE | OpenAI API base URL | Optional |
| ANKI_DECK_NAME | Anki deck name | "Vocabulary" |
| ANKI_MODEL_NAME | Anki template name | "Basic" |
| ANKI_CONNECT_URL | AnkiConnect URL | "http://localhost:8765" |
## Project Structure
```
.
├── data/
│ ├── audio/ # Audio file cache
│ └── vocabulary.csv # Vocabulary data storage
├── logs/ # Log files
├── src/
│ └── index.ts # Main program
└── package.json
```
## Development Guide
1. Start development mode:
```bash
npm run dev
```
2. View logs:
```bash
tail -f logs/anki-mcp-YYYY-MM-DD.log
```
## Anki Template Configuration
Before using this tool, need to create correct card template in Anki. Please follow steps to configure:
1. Create a new note type in Anki (Tools -> Manage Note Types -> Add)
2. Add following fields:
- Word
- WordAudio
- Definition
- DefinitionAudio
- Example
- ExampleAudio
3. Configure card template:
### Front Template
```html
<div class="container">
<div class="word">{{Word}}</div>
<div class="audio-wrapper">{{WordAudio}}</div>
</div>
```
### Back Template
```html
<div class="container">
<!-- Word section -->
<div class="header">
<div class="word">{{Word}}</div>
<div class="audio-wrapper">{{WordAudio}}</div>
</div>
<!-- Definition section -->
<div class="section">
<div class="label">Definition</div>
<div class="content">{{Definition}}</div>
<div class="audio-wrapper">{{DefinitionAudio}}</div>
</div>
<!-- Example section -->
<div class="section">
<div class="label">Example</div>
<div class="content">{{Example}}</div>
<div class="audio-wrapper">{{ExampleAudio}}</div>
</div>
</div>
```
### Style Sheet
```css
.card {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
background-color: #ffffff;
color: #2c3e50;
line-height: 1.6;
}
.container {
padding: 30px;
max-width: 800px;
margin: 0 auto;
}
.header {
text-align: center;
margin-bottom: 40px;
padding-bottom: 30px;
border-bottom: 1px solid #eee;
}
.word {
font-size: 36px;
font-weight: 700;
color: #1a1a1a;
margin-bottom: 10px;
letter-spacing: 0.5px;
}
.section {
margin-bottom: 35px;
padding: 20px;
background-color: #f8f9fa;
border-radius: 12px;
box-shadow: 0 2px 4px rgba(0,0,0,0.05);
}
.label {
font-size: 20px;
font-weight: 600;
color: #666;
margin-bottom: 12px;
text-transform: uppercase;
letter-spacing: 1px;
}
.content {
font-size: 22px;
color: #2c3e50;
line-height: 1.7;
padding: 0 10px;
}
/* Hide audio controls */
.audio-wrapper {
height: 0;
width: 0;
opacity: 0;
overflow: hidden;
position: absolute;
}
/* Responsive design */
@media (max-width: 480px) {
.container {
padding: 20px;
}
.word {
font-size: 32px;
}
.content {
font-size: 20px;
}
}
/* Night mode support */
.nightMode .card {
background-color: #1a1a1a;
color: #ffffff;
}
.nightMode .section {
background-color: #2d2d2d;
}
.nightMode .word {
color: #ffffff;
}
.nightMode .label {
color: #aaaaaa;
}
.nightMode .content {
color: #dddddd;
}
```
4. Set `ANKI_MODEL_NAME` to your created template name in environment variables
## Precautions
1. Ensure Anki and AnkiConnect plugin are running
2. Audio files will be cached in `data/audio` directory automatically
3. Vocabulary data stored in `data/vocabulary.csv`
4. Detailed logs stored in `logs` directory
## Screenshots
## License
ISC
