Kani MCP Server

Kani MCP Server

<!-- mcp-name: io.github.Alexxanddr/kani-mcp-server -->

A small, read-only Model Context Protocol server that gives MCP clients access to a user's WaniKani progress and WaniKani reference data through the official API v2.

It can answer questions such as:

• What reviews and lessons are coming up today?
• Which kanji are assigned at a given level?
• Which subjects have the lowest review accuracy?
• What notes or synonyms have I saved?

The server runs locally over stdio. It does not store data, expose an HTTP service, or modify WaniKani.

Requirements

• Node.js 18 or newer
• A WaniKani personal access token with read-only permissions, created in WaniKani API Tokens

Keep the token secret. It grants access to account and study data.

Install

The simplest MCP configuration runs the published package directly with npx:

{
  "mcpServers": {
    "wanikani": {
      "command": "npx",
      "args": ["-y", "kani-mcp-server@latest"],
      "env": {
        "WANIKANI_API_TOKEN": "your-read-only-token"
      }
    }
  }
}

Alternatively, install the executable globally:

npm install --global kani-mcp-server
kani-mcp-server

Restart the MCP client after changing its configuration. Prefer the client's secure secret facility, when available, over writing a token into a JSON file.

Run from source

git clone https://github.com/Alexxanddr/kani-mcp-server.git
cd kani-mcp-server
npm ci
cp .env.example .env
# Edit .env and set WANIKANI_API_TOKEN.
npm run build
node --env-file=.env dist/index.js

To configure an MCP client against a source checkout, replace the path and token:

{
  "mcpServers": {
    "wanikani": {
      "command": "node",
      "args": ["/absolute/path/to/kani-mcp-server/dist/index.js"],
      "env": {
        "WANIKANI_API_TOKEN": "your-read-only-token"
      }
    }
  }
}

The process communicates via MCP on stdin/stdout, so an empty terminal after startup is normal.

Tools

Collection tools return one API page. Use pageafterid or pagebeforeid from the WaniKani collection pagination data to continue. Arrays are sent as the comma-delimited filters expected by the API.

Example prompts:

Show my WaniKani level and the reviews due in the next 24 hours.
List my level 10 kanji assignments and explain their current SRS stages.
Find review statistics below 70%, then fetch the matching subjects.

See MCP contracts for exact inputs and outputs.

Configuration

Changing the base URL sends the bearer token to that host. Remote overrides must use HTTPS; localhost HTTP is accepted for tests and local development.

Development

npm ci
npm run check
npm pack --dry-run

Shortened. The full README is on GitHub.