mcp-server-maimemo

An MCP (Model Context Protocol) server for the 墨墨背单词 (Maimemo) Open API. It exposes every documented API capability as a typed MCP tool, so AI assistants can look up words, manage mnemonics / interpretations / example sentences, maintain cloud notepads, and read or modify study plans.

Highlights

• Complete API coverage — 24 tools spanning all six documented resource groups.

• Streamable HTTP transport — the current MCP spec, at POST /mcp. The deprecated HTTP+SSE transport is still served at GET /sse for older clients.

• Per-request tokens — clients may send Authorization: Bearer <maimemo_token>, so one deployment can safely serve multiple users. Each session gets an isolated API client.

• Built-in rate limiting — a multi-window sliding log shapes traffic to Maimemo's quotas (10s/20, 60s/40, 5h/2000 by default) instead of letting the model hit random 429s.

• Retries, timeouts, and caching — exponential backoff with jitter on transient failures, per-request timeouts, and a bounded spelling → voc_id cache that removes redundant lookups.

• Schema-validated inputs — tools are declared once as zod schemas and projected into JSON Schema, so advertised contracts and runtime validation cannot drift apart.

• Actionable errors — failures come back as typed, human-readable isError results (auth, rate_limit, not_found, invalid_input, …) so the model can self-correct.

Related MCP server: memos-mcp-server

Tools

Word-scoped tools accept either word (a spelling, resolved automatically and cached) or a raw voc_id. Read-only tools are annotated with readOnlyHint, and delete tools with destructiveHint, so clients can gate them appropriately.

Getting a token

In the Maimemo app: 我的 → 更多设置 → 实验功能 → 开放 API

Quick start

git clone https://github.com/Mrquj/mcp-server-maimemo.git
cd mcp-server-maimemo
npm install
npm run build

cp .env.example .env   # then fill in MAIMEMO_API_TOKEN
npm start

Verify it is up:

curl http://localhost:3000/healthz

Docker

docker build -t mcp-server-maimemo .
docker run -p 3000:3000 -e MAIMEMO_API_TOKEN=your_token mcp-server-maimemo

Configuration

Invalid configuration fails fast at startup with an explicit message.

Connecting clients

Remote clients (Notion, and other hosted MCP clients)

Deploy behind HTTPS, then register the MCP server URL:

https://your-domain.example.com/mcp

If you set MAIMEMO_REQUIRE_CLIENT_TOKEN=true, configure the connection's Bearer token to your Maimemo API token. Otherwise the server falls back to MAIMEMO_API_TOKEN.

Local clients (Claude Desktop, and similar)

{
  "mcpServers": {
    "maimemo": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-maimemo/dist/index.js"],
      "env": {
        "MAIMEMO_MCP_TRANSPORT": "stdio",
        "MAIMEMO_API_TOKEN": "your_token_here"
      }
    }
  }
}

MCP Inspector

npm run inspect

Endpoints

Example calls

{ "name": "get_vocabulary", "arguments": { "word": "apple" } }
{ "name": "create_note", "arguments": { "word": "apple", "note_type": "谐音", "note": "阿派" } }
{ "name": "add_words", "arguments": { "spellings": ["apple", "banana"], "advance": true } }
{ "name": "get_study_progress", "arguments": {} }

Notepad content uses Maimemo's markup:

#DESC
Words from this week's reading
#LIST
apple
banana
cherry

Architecture

src/
  config.ts        Environment parsing and fail-fast validation
  errors.ts        Typed error hierarchy and HTTP status mapping
  rate-limiter.ts  Multi-window sliding-log throttle
  client.ts        Maimemo API client: retries, timeouts, voc_id cache
  tools.ts         zod schemas → JSON Schema + tool annotations
  handlers.ts      Validated dispatch to Maimemo endpoints
  server.ts        MCP server factory
  http.ts          Streamable HTTP + legacy SSE + health, graceful shutdown
  index.ts         Entry point and transport selection

License

MIT