A vocabulary-bank MCP server. Use it from Claude Desktop (or any MCP host) to collect unfamiliar words while you read or chat, organise them into decks, review them on a spaced-repetition schedule, enrich them with definitions and examples, and even hear them pronounced — all stored locally on your machine.
- Save while you read. Hand any word to Claude — it saves the spelling, definition, phonetic, example, source sentence, and tags.
- Spaced repetition. Pure-Python SM-2 algorithm tracks mastery and the next review date for each word.
- Multiple decks. Group words by topic, exam, language, or project. The same word can live in different decks with different definitions.
- Quizzes that adapt. Multiple-choice, fill-in-the-blank, and definition-match. Claude (the host) writes the questions itself — no API key needed.
- Content enrichment.
enrich_wordfills in definition / phonetic / part-of-speech / synonyms / antonyms. By default Claude does it from its own knowledge; opt into the freedictionaryapi.devlookup withuse_api=True. - Pronunciation.
pronounce_wordreturns an MP3 audio block via gTTS (multilingual, no API key, cached locally). - MCP resources & prompts. Browse decks, due lists, and stats as
vocab://...resources; trigger a daily review or vocab capture from a passage with one prompt.
pip install vocab-mcp # core only pip install "vocab-mcp[tts]" # + gTTS pronunciations pip install "vocab-mcp[enrich]" # + dictionaryapi.dev lookup pip install "vocab-mcp[all]" # everything
Python 3.10+. macOS / Linux / Windows.
Edit (or create) ~/Library/Application Support/Claude/claude_desktop_config.json
on macOS — equivalent paths exist on Windows and Linux:
{
"mcpServers": {
"vocab": {
"command": "vocab-mcp"
}
}
}Restart Claude Desktop fully (⌘Q on macOS). The new tools should appear in the tools panel.
If vocab-mcp isn't on your PATH (e.g. you installed into a conda env), use
the absolute path:
{
"mcpServers": {
"vocab": {
"command": "/path/to/python",
"args": ["-m", "vocab_mcp"]
}
}
}| Tool | Purpose |
|---|---|
save_word |
Save one word into a deck. |
save_words_batch |
Save many words at once. |
set_word_fields |
Patch existing fields on a word. |
enrich_word |
Get definition / phonetic / POS / synonyms / antonyms. |
pronounce_word |
Synthesize a pronunciation MP3 (requires [tts]). |
list_words / search_word / get_stats |
Browse a deck. |
list_decks / create_deck / delete_deck |
Manage decks. |
get_due_words / generate_quiz / submit_quiz_result |
Review flow. |
vocab://decks— index of all decksvocab://decks/{name}— full contents of a deckvocab://decks/{name}/due— words due in a deckvocab://decks/{name}/stats— per-deck statsvocab://stats— library-wide stats
daily_review(deck, limit)— start a review sessioncapture_vocab(passage, deck)— extract candidate words from a passagequiz_session(deck, count, quiz_type)— ad-hoc quiz session
> "create a deck called gre"
> "I'm reading <passage>. Save any high-utility words to gre."
> "what's due in gre today?"
> "quiz me on 10 gre words"
> "show me library stats"
Everything lives at ~/.vocab-mcp/:
~/.vocab-mcp/
├── vocab.db # SQLite database
└── audio/ # cached pronunciation MP3s
Override with VOCAB_DATA_DIR=/some/dir (or just the database path with
VOCAB_DB_PATH=/some/file.db).
The database is per-user, local, and never uploaded anywhere. Two users on the same machine using different OS accounts each get their own DB.
git clone https://github.com/Code-byte404/vocab-mcp cd vocab-mcp python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" ruff check . pytest
CI runs the same checks across Python 3.10–3.12 on Ubuntu and macOS.
See CONTRIBUTING.md. Issues and PRs welcome — please file an issue before sending large changes.
MIT.