# Vocabit [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/JohnBilousov/vocabit-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 199  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/vocabit

## Description
Create flashcard sets in the Vocabit app and read back how the learner actually did.

## Tools
Capabilities this server exposes over MCP:

- **vocabit_health** — Check the connection and which mode the server is in.
- **create_study_set** — Publish a set to the learner's app. Returns a deep link that opens it on the device.
- **list_study_sets** — Recent sets, newest first, each with a progress summary.
- **get_study_set** — Full contents of one set, plus the topic and notes the assistant attached.
- **get_set_results** — The feedback half.** Per-card status, `weakCards`, `untouchedCards`, due cards.
- **update_study_set** — Retitle, retag, or append cards — typically the follow-up after reading results.
- **notify_learner** — Telegram ping that a set is waiting.
- **delete_study_set** — Remove a set from the app. Study history is kept.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "vocabit": {
    "command": "npx",
    "args": ["-y","vocabit-mcp"],
    "env": {
      "VOCABIT_BASE_URL": "",
      "VOCABIT_AGENT_KEY": "",
      "VOCABIT_USER_ID": "",
      "VOCABIT_TERM_LANGUAGE": "",
      "VOCABIT_DEFINITION_LANGUAGE": "",
      "VOCABIT_TELEGRAM_ID": "",
      "VOCABIT_TIMEOUT_MS": "",
      "VOCABIT_DEMO": ""
    }
  }
}
```

**Requires environment variables:** `VOCABIT_BASE_URL`, `VOCABIT_AGENT_KEY`, `VOCABIT_USER_ID`, `VOCABIT_TERM_LANGUAGE`, `VOCABIT_DEFINITION_LANGUAGE`, `VOCABIT_TELEGRAM_ID`, `VOCABIT_TIMEOUT_MS`, `VOCABIT_DEMO` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What the Vocabit MCP server does

The Vocabit MCP server gives an AI assistant a complete study-set loop: generate cards, publish them to the Vocabit app, inspect what the learner studied, and revise the material afterward. A created set returns a deep link that can open the set on the learner’s device. The assistant can also attach a topic and notes to a set for later context.

Progress comes from Vocabit’s spaced-repetition engine rather than an assistant-generated estimate. Cards can be reported as new, struggling, learning, or mastered. A set becomes completed when no cards remain new. Study history remains available after a set is deleted.

## How it works

The server exposes MCP tools over a stdio transport. In live mode, an HTTP client sends requests to a configured Vocabit backend and identifies itself with an agent key. In demo mode, an in-memory client provides the same tool surface with two seeded sets and a deterministic simulated learner, making it possible to test the workflow without an account or backend.

The usual loop starts with `create_study_set`, followed by learner activity in the Vocabit app. `get_set_results` then returns per-card statuses, weak cards, untouched cards, due cards, and review information. An assistant can use those results to call `update_study_set`, commonly by appending cards or changing the title or tags. The `study-session` prompt is available to guide the full sequence.

## Setup and configuration

Run the published package with `npx -y vocabit-mcp`. With neither live connection variable set, the server starts in demo mode. To connect to a real backend, set both `VOCABIT_BASE_URL` and `VOCABIT_AGENT_KEY`; the key must match one of the backend’s configured agent API keys. Supplying only one of those values causes startup to fail rather than selecting a partial configuration.

Optional settings include the learner’s Firebase UID, default term and definition languages, a Telegram recipient, and an HTTP timeout. `VOCABIT_DEMO=1` explicitly selects demo mode. The default request timeout is 20,000 milliseconds.

For inspection without a host application, run the server through the MCP Inspector in demo mode. Claude Code can add it with `claude mcp add vocabit -- npx -y vocabit-mcp`, while Claude Desktop and other MCP clients can use an equivalent stdio configuration.

## Tools and capabilities

- `vocabit_health` reports connection status and the active mode.
- `create_study_set` publishes a set and returns its device deep link.
- `list_study_sets` returns recent sets with progress summaries.
- `get_study_set` retrieves a set’s cards, topic, and attached notes.
- `get_set_results` reports card-level outcomes, weak and untouched cards, due cards, and review data.
- `update_study_set` changes metadata or appends cards.
- `notify_learner` sends a Telegram notification that a set is available.
- `delete_study_set` removes a set while retaining its study history.

The `vocabit://set/{setId}` resource exposes a set as JSON, and the server includes a `study-session` prompt for the end-to-end workflow. Read-only tools are annotated as such, while deletion is marked as destructive.

## Limitations and notes

The server depends on a Vocabit backend with its agent API enabled for live use. Multi-learner support without a backend default UID, streamable HTTP transport, and audio pronunciation cards are listed as roadmap items rather than current capabilities. Telegram notification contacts a real person, so `notify_learner` should be used deliberately. Demo learner activity is simulated and marked in responses; it should not be treated as real learner performance.

_Full upstream README: https://allmcps.com/mcp/vocabit/readme_