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.

MCP Servers