memrise-mcp
# memrise-mcp
Connect Claude to your Memrise account, so Claude knows which words you've learned, how well you know them, and which lessons they come from. Then it can quiz you, explain things using words you already know, or write practice texts at your level.
> **Unofficial.** This is a personal project, not made or endorsed by Memrise. It relies on the way Memrise's website works today, so it may stop working if Memrise changes something. Use it only with your own account, at your own risk.
## What you can ask
Once it's set up, just talk to Claude about your Memrise learning. For example:
- "Which Memrise lessons did I finish this month, and what were they about?"
- "Quiz me on the words from my last Memrise lesson."
- "Which of my Memrise words do I find difficult?"
- "Do I already know these words from Memrise: *casa, janela, cozinha*?"
- "Write me a short story using only words I've learned in Memrise."
Claude can only **read** your Memrise data. It never changes anything in your account: no reviews, no progress, no settings.
## What you need
- The [Claude Desktop app](https://claude.ai/download) on a Mac, Windows or Linux.
- A Memrise account that you log into with an **e-mail and password**. If you signed up with Google, set a password first, for example with "Forgot password" on Memrise's sign-in page.
- **Node.js**, a free program that runs this tool. Download the "LTS" version from [nodejs.org](https://nodejs.org) and install it like any other app.
## Set it up
1. **Open Claude's settings file.** In Claude Desktop, go to **Settings → Developer → Edit Config**. This opens (or shows you) a file called `claude_desktop_config.json`.
2. **Paste the connection details.** If the file is empty, or contains only `{}`, replace everything in it with:
```json
{
"mcpServers": {
"memrise": {
"command": "npx",
"args": ["-y", "github:volodymyrkoval/memrise-mcp"],
"env": {
"MEMRISE_USERNAME": "your-email@example.com",
"MEMRISE_PASSWORD": "your-memrise-password"
}
}
}
}
```
If the file already has an `"mcpServers"` section, add only the `"memrise": { … }` part inside it, and put a comma between it and the entry before it.
3. **Put in your own login.** Replace `your-email@example.com` and `your-memrise-password` with your Memrise e-mail and password. Keep the quotation marks.
4. **Save the file, then quit Claude completely** (on a Mac: **Claude → Quit**, or ⌘Q; on Windows: **File → Exit**, and if Claude keeps running, right-click its icon near the clock and choose **Quit**, or end it in Task Manager; on Linux: quit it from its menu or tray icon) **and open it again.**
5. **Try it.** Ask Claude: *"List my Memrise courses."*
The very first question takes a while, up to a minute or two: the tool downloads itself and then reads all your lessons once. After that, answers come quickly.
**Learning more than one language on Memrise?** Ask Claude to list your Memrise courses and note the number of the one you want. Then add a line with that number below your password, in the same file:
```json
"MEMRISE_LANGUAGE_PAIR_ID": "12345"
```
(Put a comma at the end of the password line before it.) Save, quit and reopen Claude.
## Be gentle with Memrise
This tool uses Memrise's website the way the website itself does. Memrise doesn't offer this as an official service and has never said how much use is acceptable. Heavy use could get your account blocked, or this tool blocked for everyone. So the tool works slowly and politely on purpose: one request at a time, with pauses, and it remembers what it has already fetched instead of asking again.
You can help:
- **Don't ask Claude to check Memrise over and over in a loop**, or set up anything that does so automatically.
- **Your word list refreshes at most once an hour.** Words you learned in the last hour may not show up yet. That's intentional.
- **If Claude reports that Memrise is "rate-limiting" you, stop** and try again later.
## Your privacy
- **Your password is stored in Claude's settings file** on your computer, as plain text. Anyone who can use your computer account could read it. Use a password you don't use anywhere else.
- **What Claude reads becomes part of your conversation.** Like anything else you share with Claude, your words and lessons are sent to Claude while you chat.
- **The tool keeps a copy of your learning data on your computer**, in a folder called `memrise-mcp` (on a Mac or Linux, inside the hidden `.cache` folder in your home folder; on Windows, inside `%LOCALAPPDATA%`), so it doesn't have to ask Memrise every time. It holds your words, your lessons and a login token, never your password.
- Nothing is sent anywhere else.
## If something goes wrong
- **Claude doesn't seem to know about Memrise.** Make sure you saved the settings file and *fully* quit and reopened Claude. Then ask: "List my Memrise courses."
- **"Memrise login failed".** Check the e-mail and password in the settings file. Try logging into memrise.com with the same details. If you signed up with Google, you may need to set a password first.
- **Claude says the Memrise tool failed to start.** Check that Node.js is installed: quit Claude, install Node.js from [nodejs.org](https://nodejs.org) (or reinstall it), and open Claude again. On Windows, if Node.js is installed and it still fails, change `"command": "npx"` and `"args"` in the settings file to:
```json
"command": "cmd",
"args": ["/c", "npx", "-y", "github:volodymyrkoval/memrise-mcp"],
```
- **The first question timed out.** Just ask again. The tool keeps what it has already fetched, so each try gets further.
- **"Rate-limiting" or "HTTP 429".** Memrise asked the tool to slow down. The message says when to try again; wait until then.
- **"Timed out waiting for another memrise-mcp process".** Another program using the tool (for example a scheduled export) is busy. Wait a few minutes and ask again.
## Removing it
1. Open the settings file again (**Settings → Developer → Edit Config**) and delete the `"memrise": { … }` part. Save, then quit and reopen Claude.
2. Delete the tool's saved data: the `memrise-mcp` folder. On a Mac, it is inside the hidden `.cache` folder in your home folder: in Finder choose **Go → Go to Folder…**, type `~/.cache`, press Return, and move `memrise-mcp` to the Trash. On Windows, press **Windows+R**, type `%LOCALAPPDATA%`, press Enter, and delete the `memrise-mcp` folder. On Linux, run `rm -rf ~/.cache/memrise-mcp`.
---
## Advanced
[](https://github.com/volodymyrkoval/memrise-mcp/actions/workflows/ci.yml)
Everything below is for developers and people using other AI tools. Running the server needs Node.js 20 or newer.
### Other MCP clients
The server speaks MCP over stdio; any MCP client can run it. For Claude Code:
```sh
claude mcp add memrise \
-e MEMRISE_USERNAME='<your-memrise-login>' \
-e MEMRISE_PASSWORD='<your-password>' \
-- npx -y github:volodymyrkoval/memrise-mcp
```
To try it without a client: `npx @modelcontextprotocol/inspector -e MEMRISE_USERNAME=... -e MEMRISE_PASSWORD=... npx -y github:volodymyrkoval/memrise-mcp`.
If a desktop app can't start the server, it may be launching it with a minimal `PATH`: use the absolute path of `npx` (`which npx`) as `command`.
### Updating and pinning
`github:volodymyrkoval/memrise-mcp` runs the latest code from the default branch. To pin a release, add a tag: `github:volodymyrkoval/memrise-mcp#v0.1.0` (see the Releases page). `npx` caches what it downloads, so to move to a newer version change the tag, or delete npx's cache (`rm -rf ~/.npm/_npx`) and restart the client.
### Settings (environment variables)
| Variable | Meaning |
|----------|---------|
| `MEMRISE_USERNAME`, `MEMRISE_PASSWORD` | Your login. Required for any data call. |
| `MEMRISE_LANGUAGE_PAIR_ID` | Which course to read. Only needed if the account has several. |
| `MEMRISE_CACHE_DIR` | Cache folder (absolute path). Default: macOS and Linux `$XDG_CACHE_HOME/memrise-mcp`, else `~/.cache/memrise-mcp`; Windows `%LOCALAPPDATA%\memrise-mcp`. |
| `MEMRISE_WORDS_TTL_SECONDS` | How long the word list is cached. Default `3600`; `0` turns it off (debugging only). |
| `MEMRISE_DEBUG` | `1` writes debug lines to stderr. |
### Load and caching
- One request at a time, at least 0.3 s apart, across every process sharing the cache folder.
- Retries network errors and 5xx up to 3 attempts. On HTTP 429 it waits as long as `Retry-After` asks (60 s if absent), retries once, then fails and records a cooldown that every process respects. A wait over 2 minutes fails at once, and no cooldown lasts more than 24 hours.
- Cache: the login token until Memrise rejects it; details of completed lessons forever (a finished lesson never changes; incomplete ones are re-fetched); the word list for `MEMRISE_WORDS_TTL_SECONDS`.
- A cold cache costs about one request per completed lesson, plus one page per 50 words and one page per 20 lessons (completed and in-progress lessons are listed separately), plus 2 login requests when there is no saved token (none with one) and 1 more to find the course when `MEMRISE_LANGUAGE_PAIR_ID` is not set.
- A warm cache still lists the lessons again each time the server starts (one page per 20 lessons) and re-fetches unfinished lessons; it asks for nothing else until the word list expires.
- Cache folder contents: `session.json` (login token), `words-*.json` (word lists), `scenario-details/` (one file per lesson), `pacer.lock` and `pacer.json` (request pacing across processes), `rate-limit.json` (the 429 cooldown).
- For scheduled jobs, run `export` once a day and read the file instead of polling.
### Export
```sh
memrise-mcp export --out words.json [--state any|fully_learned_or_known] [--include-audio]
```
Writes your words, lessons and a `fetched_at` timestamp to one JSON file. It always fetches the word list fresh, then saves it to the cache shared with the server, so it also warms it.
### Tool reference
| Tool | What it does |
|------|--------------|
| `language_pairs_list` | Your language pairs and their ids. |
| `learnables_list` | Your words, with lessons and topics. Pages of 200 by default; when `truncated` is true, call again with `after_id` set to `next_after_id`. |
| `learnables_lookup` | Checks whether given words or phrases appear among your words (ignores case, accents and a leading article). |
| `scenarios_list` | Your lessons, newest first. Filter with `type` (`completed` or `in_progress`) and `since`. |
| `scenario_learnables` | The words of one lesson. |
`state` (on word tools) is `any` (everything you have met, the default) or `fully_learned_or_known`. If some lesson details cannot be fetched, results still come back with a `warnings` field.
### Security details
- The password is read from the environment and never written to disk. Only a login token is cached, in `session.json`; anyone who can read it can read your Memrise data. On macOS and Linux the file mode is `0600` and the folder `0700`. Windows does not enforce these modes: there the token file is protected only by the default permissions of your user profile.
- Logs and errors never contain the username, password or tokens.
- The cache and export files hold learning data; don't share them.
### Development
```sh
npm install
npm test # offline unit tests
npm run test:realfs # real-filesystem tests: two processes sharing one cache folder
npm run smoke:startup # packs the server, starts it like npx does, lists the 5 tools
npm run typecheck
npm run build
npm run check-secrets
```
Developing needs Node.js 22.18 or newer (vitest 5 and tsup 9 require it).
See [AGENTS.md](AGENTS.md) for contributor and AI-agent guidance. Test fixtures are invented data. `npm run smoke` runs a live check when credentials are set and is skipped otherwise.
TDQS
Scored across 5 tools
The tools map to clearly distinct resources and actions: language pairs, learnable words, term checks, scenario lists, and per-scenario word lists. The only potential overlap is between learnables_list and learnables_lookup, but their descriptions clearly distinguish browsing all words from checking specific terms.
All names use snake_case and mostly follow a resource_action pattern such as language_pairs_list, learnables_list, learnables_lookup, and scenarios_list. scenario_learnables is the minor outlier, using a singular resource and noun-like ending instead of a clear action.
Five tools is well within the ideal 3-15 range and each one serves a distinct step in browsing a Memrise account. There are no obviously redundant or filler tools.
The read-only surface covers language pairs, word listing and lookup, lesson listing, and lesson word details, which are the core Memrise query workflows. Minor gaps such as no direct single-scenario metadata tool are workable through the existing list operations.