Content
# Anki MCP Vocabulary Manager
An intelligent Anki vocabulary management tool based on MCP (Model Context Protocol), supporting automatic pronunciation generation, intelligent search, and statistical analysis.
## Features
- Intelligent Vocabulary Management
- Batch add words and individual add
- Automatically generate pronunciation for words, definitions, and example sentences (OpenAI TTS)
- Supports tag system and note-taking features
- CSV format storage, supports version control to prevent word loss
- Advanced Search and Analysis
- Multi-dimensional sorting: due date, recent review, difficulty, etc.
- Intelligent search: supports fuzzy matching of words and definitions
- Detailed statistics: review count, accuracy, familiarity, etc.
- Automation Tools
- Fully automated Anki card creation
- Intelligent audio caching system
- Detailed logging
## Tool Commands
### add-words-batch
Add words to the vocabulary and create Anki cards (supports single and batch operations)
Input:
- words: Array of words, each containing:
- word: Word (English only)
- definition: Definition (English only)
- example: Example sentence (optional, English only)
- notes: Notes (optional, English only)
- tags: Array of tags (optional, supports only letters, numbers, hyphens, and underscores)
### list-words
List words in Anki, supporting multiple sorting methods:
- due: Sort by due date (unfamiliar words first)
- recent: Sort by review frequency (most recently reviewed first)
- difficulty: Sort by accuracy (most challenging first)
- added: Sort by creation time (newest added first)
- lapses: Sort by forgetting count (most frequently forgotten first)
### search-words
Search for words and definitions in the Anki deck
Input:
- query: Search keyword
- limit: Number of results to return (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 the top menu Tools -> Add-ons
3. Click the "Get Add-ons..." button
4. Enter the plugin code: `2055492159`
5. Click OK to install
6. Restart Anki for the plugin to take effect
7. Verify installation:
- Ensure Anki is running
- Visit `http://localhost:8765` in your browser
- If you see a blank page or a JSON response, the plugin is installed successfully
## Quick Start
1. Clone the repository:
```bash
git clone <repository-url>
cd anki-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build the 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": "你的OpenAI API密钥",
"OPENAI_API_BASE": "可选的API基础URL",
"ANKI_DECK_NAME": "你的Anki牌组名称",
"ANKI_MODEL_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 model 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, you need to create the correct card template in Anki. Follow these steps to configure:
1. Create a new note type in Anki (Tools -> Manage Note Types -> Add)
2. Add the following fields:
- Word
- WordAudio
- Definition
- DefinitionAudio
- Example
- ExampleAudio
3. Configure the 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">
<!-- 单词部分 -->
<div class="header">
<div class="word">{{Word}}</div>
<div class="audio-wrapper">{{WordAudio}}</div>
</div>
<!-- 释义部分 -->
<div class="section">
<div class="label">Definition</div>
<div class="content">{{Definition}}</div>
<div class="audio-wrapper">{{DefinitionAudio}}</div>
</div>
<!-- 例句部分 -->
<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;
}
/* 隐藏音频控件 */
.audio-wrapper {
height: 0;
width: 0;
opacity: 0;
overflow: hidden;
position: absolute;
}
/* 响应式设计 */
@media (max-width: 480px) {
.container {
padding: 20px;
}
.word {
font-size: 32px;
}
.content {
font-size: 20px;
}
}
/* 夜间模式支持 */
.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` in the environment variables to the name of the template you created
## Notes
1. Ensure Anki and the AnkiConnect plugin are running
2. Audio files are automatically cached in the `data/audio` directory
3. Vocabulary data is stored in `data/vocabulary.csv`
4. Detailed logs are stored in the `logs` directory
## Screenshots
## License
ISC
