vocabit-mcp
Allows sending a Telegram notification to the learner when a study set is waiting for them.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vocabit-mcp Create a flashcard set on Spanish food, then read back the weak cards."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
vocabit-mcp
An MCP server for Vocabit, a flashcard app. It lets an AI assistant write a study set into a real app on a real phone, and then read back how the learner actually did with it.
Most MCP servers read from an API. This one closes a loop:
flowchart LR
A["Assistant<br/>teaches a topic"] --> B["create_study_set"]
B --> C["Set appears in the<br/>Vocabit app"]
C --> D["Learner works<br/>through it"]
D --> E["get_set_results"]
E -->|weak cards| AThe interesting tool is not create_study_set — anything can generate flashcards.
It is get_set_results: which cards the learner marked hard, which they never reached,
how many reviews each one took. The next set is built out of that, not out of a guess.
Try it in 30 seconds
No backend, no account, no API key:
npx -y vocabit-mcp --demoDemo mode runs the same server against an in-memory Vocabit with two seeded sets. Create a set, ask for results, and a deterministic stand-in learner will have worked through it — flagged in the response as simulated, so it is never mistaken for real data.
To poke at it with a UI:
npx @modelcontextprotocol/inspector npx -y vocabit-mcp --demoRelated MCP server: MindDory MCP Server
Install
Listed in the MCP Registry as io.github.JohnBilousov/vocabit-mcp, so clients that read the registry can find it on their own.
claude mcp add vocabit -- npx -y vocabit-mcp{
"mcpServers": {
"vocabit": {
"command": "npx",
"args": ["-y", "vocabit-mcp"],
"env": {
"VOCABIT_BASE_URL": "https://your-vocabit-backend.example.com",
"VOCABIT_AGENT_KEY": "your-agent-key"
}
}
}
}Drop the env block to run in demo mode.
Tools
Tool | What it does |
| Check the connection and which mode the server is in. |
| Publish a set to the learner's app. Returns a deep link that opens it on the device. |
| Recent sets, newest first, each with a progress summary. |
| Full contents of one set, plus the topic and notes the assistant attached. |
| The feedback half. Per-card status, |
| Retitle, retag, or append cards — typically the follow-up after reading results. |
| Telegram ping that a set is waiting. |
| Remove a set from the app. Study history is kept. |
Also exposed: the vocabit://set/{setId} resource (a set as JSON, listable) and a
study-session prompt that walks the whole loop.
Card states
Progress comes from the app's spaced-repetition engine, not from the assistant:
Status | Meaning |
| Never reviewed. |
| Learner marked it hard. |
| Marked good. |
| Marked easy. |
A set reports completed: true once no card is left in new.
Live mode
Point the server at a Vocabit backend that has the agent API enabled:
export VOCABIT_BASE_URL=https://your-vocabit-backend.example.com
export VOCABIT_AGENT_KEY=... # must match one of AGENT_API_KEYS on the backend
npx -y vocabit-mcpVariable | Purpose |
| Backend base URL. |
| Sent as |
| Firebase UID of the learner. Optional; the backend has a default. |
| Defaults for new sets, e.g. |
| Recipient for |
| Request timeout, default |
|
|
Set neither URL nor key and the server starts in demo mode. Set exactly one and it refuses to start — half a configuration is a mistake, not a hint.
Design notes
Demo mode is a first-class client, not a stub. HttpVocabitClient and
DemoVocabitClient implement the same VocabitClient interface, so no tool has a
branch for "are we pretending?". A reviewer can run the server before they have
credentials, and the test suite exercises the real tool surface over a real MCP
transport rather than mocking the SDK.
Errors are recoverable, not fatal. A failed call comes back as isError with the
backend's own message plus a hint aimed at the model — 404 says "call
list_study_sets to see which sets exist", 401 says "or run with VOCABIT_DEMO=1".
Mutually exclusive arguments are rejected with an explanation instead of a guess.
Output schemas stay loose on the edges. Identifying fields are required; everything else is optional, so a backend that grows a field does not turn a working tool into a validation error.
Annotations are honest. delete_study_set is marked destructiveHint, the read
tools readOnlyHint. notify_learner messages a real person, and its description says
to use it sparingly.
Development
git clone https://github.com/JohnBilousov/vocabit-mcp && cd vocabit-mcp
npm install
npm run build
npm test # tool surface + full loop, plus the HTTP client against a mocked fetch
npm run lint # eslint
npm run format # prettier --write
npm run inspect # demo mode in the MCP InspectorCI runs typecheck, lint, format:check, test, and build on every push and pull request.
src/
index.ts CLI entry, stdio transport
config.ts env → Config, demo-mode resolution
server.ts tool / resource / prompt registration
schemas.ts zod input and output shapes
format.ts human-readable summaries next to structuredContent
client/
types.ts wire types + VocabitClient contract
http.ts live backend
mock.ts in-memory backend for demo mode
test/
server.test.ts tool surface + full loop — over an in-memory MCP transport
client/
http.test.ts query encoding, error-body parsing, timeouts — against a mocked fetchReleasing
Publishing uses npm's trusted publishing (OIDC) —
no NPM_TOKEN secret, nothing that can leak or expire. One-time setup on npmjs.com, under the
package's Settings → Trusted publishing → GitHub Actions: organization JohnBilousov, this
repository, workflow filename publish.yml.
To cut a release: bump the version in package.json, server.json, and VERSION in
src/server.ts together (a test asserts they can't drift), commit, push, then publish a GitHub
Release with a matching vX.Y.Z tag. That triggers
.github/workflows/publish.yml, which runs the test suite and
publishes to npm with provenance — the
package page shows a verified link back to this exact commit and workflow run, not just a name on
the registry.
Roadmap
Streamable HTTP transport alongside stdio
Multi-learner support without a backend default UID
Audio pronunciation cards
License
MIT © Ivan Bilousov
Available Tools
8 toolscreate_study_setCreate a study setA
Build a flashcard set and publish it to the learner's Vocabit app. Returns a deep link that opens the set on their device. Prefer one focused topic and 8-15 cards per set — long sets get abandoned. Use the notes field for what you want to check afterwards; the learner never sees it.
Inputs: cards (required), title (required), notes, topic, +6 more. Returns: setId, title, userId, deepLink, +4 more
delete_study_setDelete a study setADestructiveIdempotent
Remove a set from the learner's app. Study history is kept on the backend, but the set disappears from their device. Ask before calling this.
Inputs: setId (required). Returns: setId, deleted
get_set_resultsGet how the learner didARead-only
Read back real study results for a set: which cards the learner marked hard (weakCards), which they never reached (untouchedCards), and per-card review counts. This is the feedback half of the loop — read it before writing the next set, and build the follow-up out of weakCards.
Inputs: setId (required), userId. Returns: cards, notes, setId, title, +7 more
get_study_setGet study set contentsARead-only
Read the full contents of a set — every card, plus the topic and notes you attached when you created it.
Inputs: setId (required). Returns: cards, notes, setId, title, +4 more
list_study_setsList study setsARead-only
List the sets you created for this learner, newest first, each with a progress summary. Use it to find a setId, or to see at a glance which sets were never opened.
Inputs: limit, topic, userId, includeProgress. Returns: sets, count
notify_learnerPing the learnerA
Send the learner a Telegram message that a set is waiting. Use sparingly — one ping per set, right after you create it.
Inputs: setId (required), text. Returns: setId, notified, telegramId
update_study_setUpdate a study setAIdempotent
Change a set in place: retitle it, retag it, or add cards. Pass addCards to append (the usual case after reviewing results) or cards to replace the list wholesale — never both. Replacing the cards resets what the learner has already studied.
Inputs: setId (required), cards, notes, title, +4 more. Returns: setId, updated, cardCount
vocabit_healthCheck Vocabit connectionARead-only
Verify the server can reach Vocabit and report which mode it is in (live backend or in-memory demo). Call this first if anything else fails.
Inputs: no named parameters. Returns: mode, baseUrl, defaultUserId
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose: health check, CRUD for study sets, results feedback, and learner notification. Even get_study_set and get_set_results are unambiguously separated—one retrieves content, the other study metrics. No two tools appear to do the same thing.
Most tools follow a verb_noun pattern (create_study_set, list_study_sets, update_study_set, delete_study_set, get_study_set, get_set_results). However, vocabit_health deviates from the verb-first style and notify_learner uses a non-set object, so the pattern is not perfectly uniform but remains predictable.
8 tools is well within the ideal 3-15 range and each earns its place in the set lifecycle. The count matches the server's scope—managing study sets with health check and notification—without redundancy or unnecessary bulk.
The tool surface covers the full lifecycle: create, read, update, delete, list, plus results feedback and learner notification. The feedback loop is closed by get_set_results informing update_study_set. Health check aids debugging. No obvious gaps that would cause agent failures.
Maintenance
Related MCP Connectors
Connects an AI assistant to your Lingard account (lingard.app), an app for learning languages with books, news and flashcards. Create topic word collections and add complete cards: translation, part of speech, pronunciation, synonyms, example sentences with translations, and images. Fill in missing fields on existing cards, rewrite example translations, and pause or resume collections, books and news in your daily study sessions. Every change can be previewed before it is saved, and saved words appear in the Lingard apps on iOS, Android and the web. Requires a Lingard account; sign-in uses OAuth.
Free: turn your AI chats into spaced-repetition vocabulary. 13 tools, reads and writes.
Create, edit and publish Educaplay educational games and quizzes from any AI assistant.
Lexpad is a vocabulary notebook with spaced repetition, in 81 languages. Connect it to ChatGPT or Claude and ask the assistant to save a word from your chat, show the words due today or quiz you. Each answer counts as practice and moves the word through its Leitner boxes. Sign-in is OAuth 2.1 with PKCE on a Lexpad page. 20 tools; the ones that overwrite or delete are marked, so the client asks first. Connecting is free. On Lexpad's Free plan the assistant writes 10 cards a day; on Pro it is unlimited, up to 1,000 a day. Guide and example prompts: https://lexpad.app/features/assistants
Related MCP Servers
AlicenseBqualityBmaintenanceEnables AI assistants to interact with the EduBase educational platform to create quizzes, upload questions, schedule exams, manage educational content, and analyze user results through natural language.153996 npm28MIT- AlicenseNot gradedqualityCmaintenanceConnects AI assistants like Claude to MindDory to automatically capture new vocabulary and grammar mistakes into spaced-repetition flashcards during language practice conversations.MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI assistants to search the Inoh dictionary and create, update, or delete vocabulary flashcards in the user's Inoh account through natural language.-
- AlicenseNot gradedqualityBmaintenanceEnables an AI assistant to act as the memory of a personal English-learning app: read progress and words due for review, run short practice conversations, and store sentences, corrections, new words, rubric scores, and checked exercises back to the user's dashboard. Also lets the assistant grow the flashcard deck and adjust word familiarity, which reschedules spaced-repetition reviews.MIT