WaniKani MCP Server

How to use

Once your MCP server is running, you connect an MCP client (such as Claude Code) to your WaniKani data. You can ask for your current status, like your level, upcoming reviews, and lesson counts, and you’ll get actionable guidance such as which items to focus on.

Typical usage patterns include asking for your live status, requesting leech items that need extra practice, and prompting your assistant to schedule or queue reviews. The system keeps data synchronized in the background so you always see up-to-date progress and forecasting.

Example end-to-end flow you can try with Claude Code once connected: start by registering your WaniKani account through the secure setup, then query for current status, and finally ask for focus recommendations based on leeches.

How to install

Prerequisites you need before installation: a workstation with Python and PostgreSQL, and a client capable of MCP connections (like Claude Code). You also need network access to run the MCP server and to connect your MCP client.

Follow these concrete steps to install and run the MCP server locally or in your chosen environment.

1. Clone the project `` git clone https://github.com/jackedney/wanikani-mcp.git ` 2. Enter the project directory ` cd wanikani-mcp ` 3. Install dependencies using the MCP package manager ` uv install ` 4. Copy the environment template and configure your database ` cp .env.example .env ` 5. Edit the database URL and other settings in .env to match your PostgreSQL setup ` # edit .env with your PostgreSQL URL, WANIKANI_API_BASE_URL, and other settings ` 6. Apply database migrations to set up the necessary schema ` uv run alembic upgrade head ` 7. Start development or HTTP server depending on your use case - For stdio (Claude Code) development ` task dev ` - For HTTP (web access) development ` task dev-http `` 8. If you are deploying in Render or a container, follow the deployment steps below, ensuring your environment variables and database connections are configured. For a basic local run, you can test connectivity with the standard commands above.

Connecting Claude Code via JSON-based MCP configuration
```
cd /path/to/wanikani-mcp
claude mcp add-json wanikani '{"command": "uv", "args": ["run", "python", "-m", "wanikani_mcp.server"], "env": {}, "cwd": "/path/to/wanikani-mcp"}'
```
Verify the connection with
```
claude mcp list
```
The wanikani entry should show as connected. Then register your WaniKani account using your API token through the appropriate prompt or command in your client, after which you will receive an MCP API key for authenticated requests.

Additional configuration and deployment notes

Configuration is designed to be straightforward. You need a PostgreSQL database and environment variables to control syncing intervals and limits. The core environment variables you’ll configure include the database URL, the base API URL for WaniKani, and timing/limit settings for sync jobs.

MCP server configuration shown in examples uses a stdio approach where the server is started through the uv tool and runs the Python module that hosts the MCP server. This keeps logs separate from direct MCP communication to avoid interference.

Security and authentication

Two-tier security protects your data. You first provide your WaniKani API token to connect your WaniKani account, then you receive an MCP API key that authenticates future requests for status, leeches, and data syncs. Each user’s data remains isolated and keys are hashed for protection.

Deployment options

Render (recommended for cloud hosting) is supported. Use the following steps to connect and deploy your MCP server.

1. Fork the project 2. Create a new Web Service in your Render account from your fork 3. Set the environment variable DATABASE_URL with your PostgreSQL connection string 4. Build with uv install 5. Start with uv run python -m wanikani_mcp.http_server 6. Run migrations with uv run alembic upgrade head

Local development is supported as well with these steps.

Local development steps for HTTP or stdio mode are presented below in command form so you can reproduce quickly.

Troubleshooting and notes

If you encounter connection issues, verify that your database URL and WaniKani API base URL are correctly configured in your .env file, and that your MCP API key has been issued after you register your WaniKani account.

Tools and data access

The MCP provides a set of actions and data endpoints to interact with your learning data. Actions include registering your user, getting the current status, retrieving leeches, and syncing data. Data endpoints provide access to detailed progress, review forecasts, and the complete item database for quick lookups.

register_user

Connect your WaniKani account securely by providing your WaniKani API token to establish an authenticated link.

get_status

Fetch the current status including level, lessons, reviews, and next review time.

get_leeches

Identify leeches, items that you consistently get wrong, to target for focused practice.

sync_data

Manual trigger to refresh data from WaniKani on-demand.

user_progress

Detailed statistics and learning metrics for the connected user.

review_forecast

Forecasts of upcoming review sessions based on your current activity.

item_database

Searchable database of your WaniKani items for quick reference.