maimemo-mcp

Personal read-only MCP server for Maimemo study data.

Features

• stdio transport for local MCP clients.

• Streamable HTTP transport at /mcp.

• Four read-only tools:

  • maimemo_get_today_progress

  • maimemo_list_today_words

  • maimemo_get_due_words

  • maimemo_find_vocabulary

  • maimemo_list_notepads

  • maimemo_get_notepad

• Bearer authentication for Maimemo OpenAPI requests.

• Local rolling-window rate limiting for the documented Maimemo limits: 20/10s, 40/60s, and 2000/5h.

• Host, origin, and optional bearer-token protection for HTTP transport.

Install

npm install
npm run build

Use Node.js 20 or newer.

Configuration

Required:

export MAIMEMO_TOKEN="your-maimemo-openapi-token"

Optional:

export MAIMEMO_BASE_URL="https://open.maimemo.com/open"
export MAIMEMO_HTTP_HOST="127.0.0.1"
export MAIMEMO_HTTP_PORT="3333"

When MAIMEMO_HTTP_HOST is not 127.0.0.1, localhost, or ::1, MCP_SERVER_AUTH_TOKEN is required:

export MCP_SERVER_AUTH_TOKEN="your-local-mcp-http-token"

Do not commit real tokens. .env files are ignored by default.

Run With Stdio

MAIMEMO_TOKEN="your-token" npx maimemo-mcp --transport=stdio

For a local checkout:

MAIMEMO_TOKEN="your-token" node dist/cli.js --transport=stdio

Example MCP client command:

{
  "mcpServers": {
    "maimemo": {
      "command": "node",
      "args": ["/absolute/path/to/momo-skills/dist/cli.js", "--transport=stdio"],
      "env": {
        "MAIMEMO_TOKEN": "your-token"
      }
    }
  }
}

Run With Streamable HTTP

MAIMEMO_TOKEN="your-token" node dist/cli.js --transport=http

Default endpoint:

http://127.0.0.1:3333/mcp

For non-loopback binding:

MAIMEMO_TOKEN="your-token" \
MAIMEMO_HTTP_HOST="0.0.0.0" \
MCP_SERVER_AUTH_TOKEN="your-local-mcp-http-token" \
node dist/cli.js --transport=http

Clients must then send:

Authorization: Bearer your-local-mcp-http-token

Tool Inputs

maimemo_get_today_progress has no input.

maimemo_list_today_words:

{
  "status": "all",
  "freshness": "all",
  "limit": 50,
  "spellings": ["hello", "world"]
}

status can be all, unfinished, or finished. freshness can be all, new, or review. limit must be between 1 and 1000.

maimemo_get_due_words:

{
  "startDate": "2026-04-18",
  "endDate": "2026-04-20",
  "spellings": ["hello"],
  "limit": 50,
  "countOnly": false
}

Dates accept YYYY-MM-DD or ISO instants. They are normalized to Asia/Shanghai before calling Maimemo.

maimemo_find_vocabulary:

{
  "spellings": ["hello"]
}

or:

{
  "ids": ["vocabulary-id"]
}

Provide exactly one of spellings or ids.

maimemo_list_notepads:

{
  "limit": 20,
  "offset": 0,
  "ids": ["notepad-id"]
}

limit must be between 1 and 100.

maimemo_get_notepad:

{
  "id": "notepad-id"
}

Returns full notepad content and parsed word list.

Development

npm test
npm run typecheck
npm run build