Skip to main content
Glama

WaniKani MCP Server

by jackedney
GitHub
Python
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

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

  2. Verify connection: Run claude mcp list - wanikani should show as "connected"

  3. Register your WaniKani account:

    Register me with WaniKani API token: your-wanikani-token

  4. 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)

  1. Fork this repository

  2. 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

  3. 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:

  1. WaniKani API Token: Your personal WaniKani API key (from wanikani.com/settings/personal_access_tokens)

  2. MCP API Key: Generated server key for Claude Code authentication

Registration Flow:

  1. Get your WaniKani API token from https://www.wanikani.com/settings/personal_access_tokens

  2. Use register_user tool with your WaniKani token

  3. Receive MCP API key for all future requests

  4. 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
F
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.

  1. ✨ Quick Start
    1. For Users with Claude Code
    2. For Developers
  2. 🎯 What This Does
    1. Architecture Overview
  3. 🔧 MCP Tools & Resources
    1. Tools (Actions)
    2. Resources (Data Access)
  4. 🚀 Deployment Options
    1. Render (Recommended)
    2. Local Development
    3. Container (Podman/Docker)
  5. 🔐 Security & Authentication
    1. ⚙️ Configuration
      1. 🧑‍💻 Development
        1. 🤝 Production Checklist
          1. 📈 Monitoring
            1. 📄 License
              1. 🙏 Acknowledgments

                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
                  12
                  MIT License
                  • Apple

                • 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 -
                  42
                  MIT License

                • Android MCP

                  CursorTouch
                  -
                  security
                  A
                  license
                  -
                  quality
                  A lightweight bridge enabling AI agents to perform real-world tasks on Android devices such as app navigation, UI interaction, and automated QA testing without requiring computer-vision pipelines or preprogrammed scripts.
                  Last updated -
                  52
                  MIT License

                • Advanced Unity MCP

                  codemaestroai
                  -
                  security
                  F
                  license
                  -
                  quality
                  A bridge that enables controlling Unity Editor through natural language commands via AI assistants, allowing users to create materials, build projects, manage scenes, and configure settings without manual interaction.
                  Last updated -
                  63
                  • Apple
                  • Linux

                View all related MCP servers

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/jackedney/wanikani-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server