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.

Related MCP server: bunpro-mcp

Install and run locally

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

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

MCP client configuration

Build the project first, then add it to any stdio-compatible MCP client. 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"
      }
    }
  }
}

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.

Tools

Collection tools return one API page. Use page_after_id or page_before_id 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

• npm run dev: run TypeScript directly over stdio

• npm test: run unit and MCP contract tests

• npm run type-check: check TypeScript without emitting files

• npm run build: create the bundled executable in dist/

Read CONTRIBUTING.md, architecture, and testing before changing public tools.

Troubleshooting

• WANIKANI_API_TOKEN is required: pass the variable in the MCP client's env block or start Node with --env-file=.env.

• 401 Unauthorized: verify the token and recreate it if it may have been exposed.

• 429 Too Many Requests: wait for WaniKani's rate-limit reset and request narrower collections.

• Large responses: add filters and paginate rather than requesting broad subject or review histories.

• Client shows disconnected: use an absolute script path, run npm run build, and confirm Node 18+ is on the client's PATH.

Limitations

• Read-only: starting assignments, submitting reviews, changing user settings, and editing study materials are intentionally absent.

• No automatic multi-page aggregation, caching, resources, or prompts.

• API response objects are passed through unchanged, so upstream additions appear without a package release.

License and distribution

This project is available under the MIT License. The npm name kani-mcp-server was available when last checked, but publishing remains intentionally disabled until the first release is approved. See publishing.

WaniKani is a trademark of Tofugu LLC. This independent project is not affiliated with, endorsed by, or sponsored by WaniKani or Tofugu.