WaniKani MCP Server

A production-ready MCP (Model Context Protocol) server that connects AI assistants like Claude Code to WaniKani learning data. Get real-time progress updates, identify problem items, and manage your Japanese learning workflow through natural conversation.

✨ Quick Start

For Users with Claude Code

Set up the MCP server connection:
cd wanikani-mcp claude mcp add-json wanikani '{"command": "uv", "args": ["run", "python", "-m", "wanikani_mcp.server"], "env": {}, "cwd": "/path/to/wanikani-mcp"}'
Verify connection: Run claude mcp list - wanikani should show as "connected"
Register your WaniKani account:
Register me with WaniKani API token: your-wanikani-token
Start learning:
How many lessons and reviews do I have? What are my worst leeches that need practice?

For Developers

git clone https://github.com/jackedney/wanikani-mcp.git
cd wanikani-mcp
uv install
cp .env.example .env  # Configure your database
uv run alembic upgrade head
task dev

🎯 What This Does

Real Learning Integration: Your AI assistant can now see your actual WaniKani progress and help with personalized study strategies.

Architecture Overview

Architecture Diagram

Core Features:

Live Status: Current level, lesson count, review count, next review time
Leech Detection: Identifies consistently difficult items for focused practice
Background Sync: Keeps data fresh automatically (every 30 minutes)
Multi-User: Secure per-user authentication with MCP API keys

Example Conversations:

You: "How am I doing with my Japanese studies?"
Claude: "You're Level 8 with 30 lessons and 206 reviews available. Your next reviews are at 11:00 PM."

You: "What should I focus on?"
Claude: "You have 15 leeches - items you consistently get wrong. Let's practice these kanji: 体, 茶, 牛..."

🔧 MCP Tools & Resources

Tools (Actions)

register_user: Connect your WaniKani account securely
get_status: Current level, lessons, reviews, next review time
get_leeches: Items that need extra practice (wrong >3 times)
sync_data: Manual data refresh from WaniKani

Resources (Data Access)

user_progress: Detailed statistics and learning metrics
review_forecast: Timeline of upcoming review sessions
item_database: Searchable collection of your WaniKani items

🚀 Deployment Options

Render (Recommended)

Fork this repository
Connect to Render:
- Create new Web Service from your fork
- Environment: DATABASE_URL (PostgreSQL connection string)
- Build: uv install
- Start: uv run python -m wanikani_mcp.http_server
Run migrations: uv run alembic upgrade head

Local Development

# Install dependencies
uv install

# Set up database
cp .env.example .env
# Edit .env with your PostgreSQL URL
uv run alembic upgrade head

# Run in stdio mode (for Claude Code)
task dev

# Run in HTTP mode (for web access)  
task dev-http

Container (Podman/Docker)

# Build
podman build -t wanikani-mcp .

# Run
podman run -p 8000:8000 \
  -e DATABASE_URL="postgresql://user:pass@host/db" \
  wanikani-mcp

🔐 Security & Authentication

Two-Tier Security:

WaniKani API Token: Your personal WaniKani API key (from wanikani.com/settings/personal_access_tokens)
MCP API Key: Generated server key for Claude Code authentication

Registration Flow:

Get your WaniKani API token from https://www.wanikani.com/settings/personal_access_tokens
Use register_user tool with your WaniKani token
Receive MCP API key for all future requests
MCP API key authenticates you for get_status, get_leeches, sync_data

Privacy: Each user's data is completely isolated. MCP API keys are securely generated and hashed.

⚙️ Configuration

Environment Variables (copy .env.example to .env):

DATABASE_URL=postgresql://user:pass@host:5432/dbname
WANIKANI_API_BASE_URL=https://api.wanikani.com/v2
SYNC_INTERVAL_MINUTES=30
MAX_CONCURRENT_SYNCS=3
RATE_LIMIT_PER_MINUTE=60
LOG_LEVEL=INFO

MCP Server Configuration (for Claude Code):

Method 1: JSON Configuration (Recommended)

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"}'

Method 2: Manual Configuration

{
  "mcpServers": {
    "wanikani": {
      "command": "uv",
      "args": ["run", "python", "-m", "wanikani_mcp.server"],
      "cwd": "/path/to/wanikani-mcp",
      "env": {}
    }
  }
}

Important:

Must specify cwd (working directory) for the server to find dependencies
Server uses file logging to avoid interfering with stdio MCP communication
Run uv install first to ensure dependencies are available

🧑‍💻 Development

Code Quality:

uv run ruff check .      # Linting
uv run ruff format .     # Formatting  
uvx ty check .           # Type checking
uv run pytest           # Testing

Database Management:

# Create migration
uv run alembic revision --autogenerate -m "description"

# Apply migrations
uv run alembic upgrade head

# Reset database (development only)
uv run python -c "from wanikani_mcp.database import reset_database; reset_database()"

Tech Stack:

Framework: FastAPI + Python MCP SDK
Database: PostgreSQL + SQLModel ORM
Background Jobs: APScheduler
Package Manager: uv
Containerization: Podman
Deployment: Render

🤝 Production Checklist

Before deploying:

PostgreSQL database configured
Environment variables set
Database migrations applied
Rate limiting configured
Monitoring/logging enabled
SSL/TLS certificates in place
Backup strategy implemented

📈 Monitoring

Health Check Endpoint: GET /health Metrics: Built-in logging for sync operations, API calls, and errors Database: Monitor connection pool, query performance, storage usage

📄 License

See LICENSE for details.

🙏 Acknowledgments

WaniKani: For providing the excellent Japanese learning platform and API
Anthropic: For the MCP specification and Claude Code integration
Python MCP SDK: For the foundational MCP implementation

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

A bridge that provides AI assistants with access to WaniKani user data and functionality, enabling them to retrieve learning progress, identify difficult items, and offer personalized Japanese language learning assistance.

Related MCP Servers

Youtube MCP Server
sparfenyuk
A
security
A
license
A
quality
Bridges YouTube API and AI assistants, enabling video analysis by downloading and processing closed captions to create summaries of YouTube videos.
Last updated -
1
11
Python
MIT License
MCP Server for Asana
cristip73
-
security
A
license
-
quality
This server implementation allows AI assistants to interact with Asana's API, enabling users to manage tasks, projects, workspaces, and comments through natural language requests.
Last updated -
547
TypeScript
MIT License
Unity-MCP
TSavo
A
security
A
license
A
quality
A bridge between Unity and AI assistants that enables AI to interact with Unity game environments through a standardized interface for code execution, scene analysis, and runtime debugging.
Last updated -
3
20
2
TypeScript
MIT License
MCP Framework
Viking1726
-
security
A
license
-
quality
A middleware system that connects large language models (LLMs) with various tool services through an OpenAI-compatible API, enabling enhanced AI assistant capabilities with features like file operations, web browsing, and database management.
Last updated -
3
Python
MIT License

View all related MCP servers

WaniKani MCP Server