vocab-mcp

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.

Features

• 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_word fills in definition / phonetic / part-of-speech / synonyms / antonyms. By default Claude does it from its own knowledge; opt into the free dictionaryapi.dev lookup with use_api=True.
• Pronunciation. pronounce_word returns 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.

Install

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.

Configure Claude Desktop

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 / Resource / Prompt reference

Tools

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.

Resources

• vocab://decks — index of all decks
• vocab://decks/{name} — full contents of a deck
• vocab://decks/{name}/due — words due in a deck
• vocab://decks/{name}/stats — per-deck stats
• vocab://stats — library-wide stats

Prompts

• daily_review(deck, limit) — start a review session
• capture_vocab(passage, deck) — extract candidate words from a passage
• quiz_session(deck, count, quiz_type) — ad-hoc quiz session

Multi-deck workflow

> "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"

Data location

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.

Development

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.

Contributing

See CONTRIBUTING.md. Issues and PRs welcome — please file an issue before sending large changes.

License

MIT.