Skip to main content
Glama
webster-dict-mcp

webster-dict-mcp

README.md
# webster-dict-mcp

An [MCP](https://modelcontextprotocol.io) server that connects AI assistants (Claude Code, Claude Desktop, Codex CLI, …) to **your Merriam-Webster account**:

- 📅 see the words you saved today (or any day)
- 🔎 search the dictionary and thesaurus, get definitions
- ⭐ save new words to your list
- 🌅 get the Word of the Day
- 🧠 practice your saved words with spaced repetition, with every answer and score tracked in SQLite

> Unofficial. It uses the same private endpoints merriam-webster.com uses in the browser, authenticated with your own login cookies. It may break if MW changes their site.

## Requirements

- Node.js **22.13+** (uses the built-in `node:sqlite`)
- `curl` on your PATH (macOS, Linux, WSL, and Windows 10+ have it)
- A merriam-webster.com account

## Install

From npm:

```sh
npm install -g webster-dict-mcp
```

Or from source:

```sh
git clone <this repo> webster-dict && cd webster-dict
npm install
```

## Configure your login

The server reads two cookies from an env file **outside the repo**, at `~/.config/webster-dict/.env` by default.

```sh
mkdir -p ~/.config/webster-dict && chmod 700 ~/.config/webster-dict
cp .env.example ~/.config/webster-dict/.env   # or create it by hand
chmod 600 ~/.config/webster-dict/.env
```

To fill it in:
1. Log in at merriam-webster.com.
2. Open DevTools → **Application** (Chrome) or **Storage** (Firefox) → **Cookies** → `https://www.merriam-webster.com`.
3. Copy two values:

```sh
MW_SESSION=<value of the MWCOMSESS cookie>
MW_REMEMBER_ME=<value of the remember_me cookie>
```

If a tool says *"session missing or expired"*, repeat these steps. The cookies are your login, so treat them like a password.

### All settings

| Variable | Default | Purpose |
|---|---|---|
| `MW_SESSION` | | `MWCOMSESS` cookie (required for account tools) |
| `MW_REMEMBER_ME` | | `remember_me` cookie (required for account tools) |
| `MW_COOKIE` | | Full raw `Cookie` header; overrides the two above. Use it if Cloudflare starts challenging requests. |
| `MW_USER_AGENT` | desktop Firefox | Should match the browser `MW_COOKIE` came from |
| `MW_CURL` | `curl` | Path to curl |
| `WEBSTER_ENV_FILE` | `~/.config/webster-dict/.env` | Where to read the variables above from |
| `WEBSTER_DB` | see [Data](#data) | SQLite database path |

Variables already set in the environment (for example by your MCP client config) win over the env file.

## Connect it to your AI

The commands below assume a global npm install. From a source checkout, replace `webster-dict-mcp` with `node /path/to/webster-dict/src/server.js`.

**Claude Code**
```sh
claude mcp add --scope user webster -- webster-dict-mcp
```

**Codex CLI**
```sh
codex mcp add webster -- webster-dict-mcp
```
or in `~/.codex/config.toml`:
```toml
[mcp_servers.webster]
command = "webster-dict-mcp"
```

**Claude Desktop** (`claude_desktop_config.json`)
```json
{ "mcpServers": { "webster": { "command": "webster-dict-mcp" } } }
```
On Windows, with the server installed inside WSL:
```json
{ "mcpServers": { "webster": {
  "command": "wsl.exe",
  "args": ["-e", "/home/<you>/.nvm/versions/node/<ver>/bin/node", "/home/<you>/path/to/webster-dict/src/server.js"]
} } }
```

**ChatGPT (web/app)** only supports remote HTTPS MCP servers, which this stdio server isn't. Use Codex CLI instead.

## Tools

| Tool | What it does |
|---|---|
| `get_daily_words({date?, include_definitions?})` | Words you saved on a day (default today) |
| `get_saved_words({page?, per_page?, search?, sort?})` | Browse your saved list. `sort` is `newest` or `alphabet` |
| `save_word({word, thesaurus?})` | Save a word. Checks the entry exists first, suggests spellings if not, and reports `already_saved` for duplicates |
| `search_words({query, thesaurus?})` | Autocomplete search plus spelling suggestions |
| `define_word({word})` | Definitions, part of speech, pronunciation, examples |
| `get_word_of_the_day()` | Featured meaning, examples, "did you know" |
| `get_practice_set({count?, source?, mode?})` | Starts a quiz session. `source` is `today`, `recent` or `all`; `mode` is `recall` or `multiple_choice`. The answer word is masked out of definitions and examples. |
| `record_practice_result({word, correct, session_id?, user_answer?})` | Logs an answer and returns the running session score |
| `get_practice_stats({sessions?})` | Overall accuracy, streak, recent session scores, daily scores, weakest and mastered words |

**Prompt:** `practice_session` (`count`, `source`, `mode`) runs a whole quiz: one question at a time, lenient grading, a score at the end compared with your recent sessions.

Things to ask your AI:
- "What words did I save today? Quiz me on them."
- "Save *sesquipedalian* to my list."
- "How have my scores been this week? Which words do I keep missing?"

## Data

Practice history is stored in SQLite:

- **source checkout:** `<project>/.dist/webster.db` (gitignored)
- **npm install:** `~/.local/share/webster-dict/webster.db`
- **override:** `WEBSTER_DB=/any/path.db`

| Table | Contents |
|---|---|
| `words` | Spaced-repetition box (1 = struggling … 5 = mastered), times seen and correct, first and last seen |
| `sessions` | One row per quiz: start time, source, mode, planned question count |
| `attempts` | Every answer: session, word, correct or not, what you typed, timestamp |

```sh
sqlite3 .dist/webster.db "SELECT word, box, correct, seen FROM words ORDER BY box"
```

## How it works

- **HTTP goes through `curl`, not Node's `fetch`.** Cloudflare challenges Node's TLS fingerprint, and curl also uses the system CA store, which matters behind corporate proxies. Cookies are passed to curl on stdin, never as arguments, so they don't appear in `ps`.
- **Saved words and saving** use MW's `/lapi/v1/wordlist/*` endpoints with your cookies.
- **Definitions and the Word of the Day** are parsed from the public HTML pages.
- **Practice** uses a Leitner system. A right answer moves a word up one box, a wrong one sends it back to box 1. Quizzes favor low-box, overdue and never-practiced words.

## Development

```sh
npm run inspect            # MCP Inspector UI against the local server
npm run check              # syntax check
node src/server.js --help
```

### Releasing

Versions follow [semver](https://semver.org) and are managed by `npm version`, which runs the checks, bumps `package.json`, commits, and tags `vX.Y.Z`. The server reads its version from `package.json`.

```sh
# 1. add the release notes under "Unreleased" in CHANGELOG.md, then commit
npm version patch          # or minor / major
git push --follow-tags
npm publish
```

## License

MIT