Japanophile MCP Server
A Japanese-learning MCP server (kanji, JLPT, vocab, culture knowledge, locale utilities) with crossconnects to speech, Calibre, and Plex.
jp_utils — convert kana between hiragana/katakana/Hepburn romaji, and convert Japanese era names to/from Western years (Meiji–Reiwa).
kanji — look up a kanji by character, search by English meaning, or filter by JLPT level (N5–N1), school grade, radical, plus random picks (13,108 kanji).
jlpt — run quiz sessions: fetch the next random question, answer it by letter (scored and recorded), and view session progress (600 questions).
vocab — search vocabulary by expression, reading, or translation, filter by JLPT level, and pull from 278k example sentences (requires the fetched 135MB kanji.db).
knowledge — list and read vendored culture pages (29 on history/travel/food/manga) or language pages (grammar, vocab, keigo, exams).
remember — review your answer history: consecutive-day streaks and a queue of questions you've missed but never gotten right.
crossconnect — speak text via speech-mcp TTS, search Sandra's Calibre library by query/tag, and search her Plex library for JP movies and anime.
japanophile_help — list tools, report data status, and suggest next steps for agents and IDEs.
Beyond MCP, the repo ships a human webapp (dashboard, Learn, Know, Games, Chat, Skills, Tools, Settings, Help, Logs) with a local-LLM japanophile-expert tutor.
Allows searching a Plex media library for Japanese movies and anime by query and media type via the crossconnect tool.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Japanophile MCP Server show me N5 kanji with the water radical"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
japanophile-mcp
Your Japanophile workstation: kanji/JLPT learning tools, Japanese culture knowledge box, travel and diary on the roadmap. First -phile repo (fleet doc: mcp-central-docs/projects/japanophile-mcp/PHILE_PATTERN.md). Polite name on listings; working title was weeaboo, retired to joke status.
Ports: backend 11193, frontend 11194. Registered in mcp-central-docs/operations/WEBAPP_PORTS.md.
Quick start (Stage 2)
cd D:\Dev\repos\japanophile-mcp
uv sync --group dev
.\start.ps1Opens http://127.0.0.1:11194 (HTTP API + MCP on 11193). MCP-only (stdio): uv run python -m japanophile_mcp.server.
Claude Desktop bundle: just mcpb-pack → dist/japanophile-mcp-v{version}.mcpb (see scripts/mcpb-pack.ps1, mcp-central-docs/standards/MCPB_PACKAGING_STANDARDS.md).
Related MCP server: Jisho MCP
Stage 1: MCP tools
Eight portmanteau tools, dialogic returns, seeds in assets/seed/, learning corpora in data/ (committed). Deliberately thin on the MCP side by design — this repo is primarily a human webapp (quizzes, games, reading), MCP tools are the agent-facing afterthought, not the product. vocab, jp_utils, and remember were added 2026-09-14 to close the gap against narrower competing MCP servers (Jisho MCP, JLPT Study MCP, Japan Utils MCP, Ayaka, Potto Japan) — see reports/quality-japanophile-mcp-2026-09-14.md:
Tool | Operations | Data |
| lookup, search, by_jlpt, by_grade, by_radical, random | assets/seed/kanji_database.db (13,108 kanji) |
| next, answer, progress | assets/seed/jlpt_questions.db (600 Q + options) |
| search (400k vocab + jmdict), by_jlpt, examples (278k example sentences) | data/kanji.db (~135MB, vendored) |
| list, get — collection=culture (29 pages) or collection=language (grammar/vocab/keigo/exams, 11 pages) | assets/knowledge/japan/.html, assets/language/.html |
| kana_convert (hiragana/katakana/romaji), era_to_year, year_to_era | pure Python — Hepburn table + Meiji-Reiwa era table |
| streak, due (missed-question queue) | data/progress.db |
| speak, library_search, media_search | proxies speech-mcp/calibre-mcp/plex-mcp REST APIs (2026-09-15, see Crossconnects below) |
| get_ui_map, tour_page, demo_webapp, diagnose_webapp | steers this repo's own webapp from |
| tool + data status | - |
No structured grammar tool: the fleet has no vendored JLPT-graded grammar-point database (unlike Ayaka/Potto Japan), and Makino/Tsutsui's grammar dictionaries are copyrighted — fabricating one would violate the no-fake-data standard. knowledge(collection=language) exposes the real vendored grammar prose page instead.
{ "mcpServers": { "japanophile-mcp": {
"command": "uv",
"args": ["run", "--directory", "D:\\Dev\\repos\\japanophile-mcp",
"python", "-m", "japanophile_mcp.server"] } } }Stage 2: webapp
Dashboard, Learn (kanji / JLPT quiz / vocab), Know, Games (vendored drills), Chat (japanophile-expert + local LLM), Skills, Tools, Settings, Help, Logs. Playwright e2e + screenshot automation in webapp/e2e/.
Webapp (for demo-vid and docs)
Page | Purpose |
Dashboard | Backend health, KPI cards for kanji seed, JLPT question bank, and knowledge page count; surfaces fetch hints when large DBs are missing |
Learn | Kanji lookup and search, JLPT quiz with scored sessions, vocabulary search when |
Know | Browse and read vendored Japan culture articles (history, travel, food, manga, and related topics) as plain text |
Games | Embedded HTML/JS practice tools: flashcards, stroke order, JLPT tests, grammar and listening drills |
Chat | Local LLM tutoring with the japanophile-expert skill loaded; routes answers through repo tools and knowledge pages (text today; voice via speech-mcp when connected) |
Skills | View the japanophile-expert skill markdown used by Chat |
Tools | One-click MCP tool runner (sample kanji lookup) for debugging and demos |
Settings | Ollama-compatible LLM endpoint and model selection for Chat |
Help | Ports, tool list, and pointers to install docs |
Logs | Sorted, filterable-style diagnostic view of backend health, database paths, and load errors from API probes |
Narrated tour script (two sentences per page, 3s pause between): docs/demo-vid/narration.yaml. demo-vid-mcp loads it automatically for demo_vid_generate(repo="japanophile-mcp").
Preview: draft PNGs + agent-made demo MP4 in docs/screenshots/README.md (better PNG contrast planned 2026-09-14).
Inheritance
Learn tools (~15 html/js games), 29 knowledge pages, kanji/JLPT seeds vendored from ai-games-collection (docs/INHERITANCE.md). Canonical home for Japanese learning; ai-games-collection keeps hanafuda/cho-han play with crosslinks.
Crossconnects
local-llm-mcp — Chat tutoring (wired).
speech-mcp — TTS via
crossconnect(speak)and the Know page's Listen button; proxied through/api/crossconnect/speak.wavso the browser never talks to speech-mcp's port directly (wired 2026-09-15).calibre-mcp —
crossconnect(library_search), Sandra's Japanese-literature/textbook/manga shelf by query or tag (wired 2026-09-15; client-side query filter works around an upstream bug — calibre-mcp's ownqueryparam is currently a no-op, see reports/quality-japanophile-mcp-2026-09-14.md follow-ups).plex-mcp —
crossconnect(media_search), Sandra's JP movies/anime by query and media_type (wired 2026-09-15; client-side type filter works around plex-mcp'smedia_typeparam currently being a no-op).ai-games-collection — canonical home for hanafuda/cho-han gameplay; this repo owns learning.
Voice Command Bus — registered as a receiver (
japanophileentity, direct route tokanji/vocab/jlpt/knowledge/japanophile_help) inmcp-central-docs/config/voice_command_bus.yaml+ fleet-agent-mcp'sFLEET_SERVERS(2026-09-15). Not yet functional — this repo's own/mcpstreamable-HTTP mount currently fails session init; fleet-agent can't reach it until that's fixed (seemcp-central-docs/standards/VOICE_COMMAND_BUS.md§4c). Seemcp-central-docs/standards/VOICE_COMMAND_BUS.mdfor the full pattern.Full crossconnect map:
mcp-central-docs/projects/japanophile-mcp/PHILE_PATTERN.md. No webapp browser UI yet for library_search/media_search — MCP/HTTP only so far.
Roadmap
Tauri NSIS winapp (installer built at 0.3.0; next release when rebased on 0.3.1).
Plan + Remember: travel planner APIs, diary, full SRS scheduler (today's
remembertool is a missed-question queue, not SM-2/FSRS).austrophile-mcp as second -phile template.
Docs: TOOLS - CONFIGURATION - INSTALL - CONTRIBUTORS
Available Tools
8 toolscrossconnectB
Fleet crossconnects: speak | voices | library_search | media_search. Each proxies a sibling MCP server's REST API (speech-mcp :10909, calibre-mcp :10720, plex-mcp :10740 by default, override via SPEECH_MCP_URL/CALIBRE_MCP_URL/ PLEX_MCP_URL). Peer offline returns a fail() with a start hint, not a traceback — see PHILE_PATTERN.md crossconnects section.
speak: text=... plays via speech-mcp's TTS on ITS OWN speaker (agent voice output), not returned audio. Defaults provider=gemini (noticeably better than Windows SAPI); pass provider="windows" if Gemini isn't configured on speech-mcp. library_search: query and/or tag against Sandra's Calibre library. media_search: query (+ optional media_type) against her Plex library.
Inputs: operation (required), tag, text, limit, +4 more. Returns: object
japanophile_helpB
List tools, data status, and next steps for agents and IDEs.
Inputs: no named parameters. Returns: object
jlptB
JLPT quiz: next | answer | progress.
next: random unseen question for level (N5..N1, falls back to any level). answer: grade question_id with letter; records to progress store. progress: session score summary.
Inputs: operation (required), level, answer, session_id, +2 more. Returns: object
jp_utilsA
Japan-locale utilities: kana_convert | era_to_year | year_to_era.
kana_convert: text=kana string, target=romaji|hiragana|katakana. Romaji is standard Hepburn (gojuon + digraphs + sokuon doubling + chouonpu vowel repeat) — see caveats in the conversion docstring. era_to_year: era=meiji|taisho|showa|heisei|reiwa, era_year=N -> western year. year_to_era: year=western year -> {era, era_year} (year-granularity; see _ERA_TABLE note on transition-year handling).
Inputs: operation (required), era, text, year, +2 more. Returns: object
kanjiB
Kanji dictionary: lookup | search | by_jlpt | by_grade | by_radical | random.
lookup: query=single kanji char. search: query=English meaning fragment. by_jlpt: level=N5..N1. by_grade: grade=1..8. by_radical: radical=char. random: optional level filter.
Inputs: operation (required), grade, level, limit, +2 more. Returns: object
knowledgeC
Knowledge box: list | get. collection=culture (default, 29 history/travel/food pages) or collection=language (grammar/vocabulary/keigo/exams/materials study pages — same vendored assets/language/ the webapp Language tab reads).
Inputs: operation (required), page, collection. Returns: object
rememberA
Review support over your own JLPT answer history: streak | due.
streak: consecutive days (ending today) with >=1 jlpt/answer logged for
session_id. due: question_ids answered at least once but never correctly —
a simple missed-question queue, NOT a full SM-2/FSRS spaced-repetition
scheduler (see PRD.md open question on SRS algorithm choice; this reads
the same data/progress.db answers table jlpt/answer writes to).
Inputs: operation (required), limit, session_id. Returns: object
vocabB
Vocabulary: search | by_jlpt | examples. Needs the big kanji.db (135MB, fetched).
search: expression/reading/translation fragment. by_jlpt: jlpt_vocabulary level. examples: query against the 278k-row examples table (Japanese sentence, English translation, linked words) — vendored with kanji.db but previously unqueried.
Inputs: operation (required), level, limit, query. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a clearly separate domain: quiz, kanji, vocabulary, knowledge, utilities, review, fleet proxies, and help. Even where subcommands like 'search' or 'by_jlpt' reappear, their target resources are explicit and non-overlapping.
Tool names are short lowercase domain labels with consistent subcommands, which is a recognizable and predictable pattern. Minor deviations like jp_utils and japanophile_help using underscores while others do not prevent a perfect score.
8 tools is well within the ideal range, and each tool bundles several related subcommands without creating namespace sprawl. Every tool earns its place in the overall Japan-study and utility workflow.
The core loop of learning kanji/vocabulary, taking JLPT quizzes, reviewing mistakes, and accessing reference material is well covered. Minor gaps exist: the review tool is deliberately not a full spaced-repetition system, and grammar material is only available as static knowledge pages rather than an interactive lookup.
Maintenance
Related MCP Connectors
Authoritative JLPT-graded Japanese dataset (kanji, vocab, grammar, history) via MCP and REST.
Jisho.org Japanese-English dictionary MCP (keyless).
Search the Inoh dictionary and create, track and delete your own vocabulary flashcards.
A Japanese shiritori (word-chain game) dictionary of 88,000+ nouns. Check whether a move is valid (including words ending in ん), suggest next words, and look up a word's reading — so an AI can play shiritori correctly.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides AI agents with direct access to local Yomitan dictionary databases for offline Japanese vocabulary lookups, kanji searches, and sentence tokenization. It leverages the Yomitan browser extension's API to enable rich dictionary interactions and Anki flashcard field generation.531 npm6Mozilla Public 2.0
- AlicenseAqualityDmaintenanceEnables Japanese word lookup and search using the Jisho.org dictionary, providing tools to search entries and retrieve exact word definitions with JLPT levels and parts of speech.23MIT
- AlicenseNot gradedqualityDmaintenanceEnables Japanese language gap analysis and remediation through adaptive probes, evidence tracking, and prerequisite-aware study queues.MIT
- FlicenseAqualityCmaintenanceA local MCP server that helps you maintain a personal Japanese learning knowledge base, including vocabulary, confusion relations, mistakes, and spaced-repetition reviews. It provides tools and prompts for managing and reviewing your Japanese learning data without calling external LLM APIs.6-