vivek081166/japan-utils-mcp

MCP server exposing **Japan-specific utilities** to AI agents (Claude, Cursor, Cline, Continue, etc.). Hand your agent the small bag of JP-specific functions every Japan-related task needs but no generic LLM gets right reliably:
- 🗓️ **Era ↔ Western year** — 令和8年 ↔ 2026
- 🔤 **Kanji → Hepburn romaji** — 山田太郎 → yamada tarou
- 📮 **Postal code lookup** — 150-0001 → 東京都 渋谷区 神宮前
- 🎌 **National holiday calendar** — is 2026-05-03 a holiday? what about all of 2026?
- 🅰️ **Kana conversion** — hiragana ↔ katakana ↔ half-width katakana
- 📏 **Width normalization** — full-width (全角) ↔ half-width (半角) for ASCII, digits, kana
- 👤 **Name splitting** — 山田太郎 → surname 山田 + given 太郎 (statistical model)
Built on top of well-maintained Japanese libraries (jpholiday, posuto, pykakasi, jaconv, namedivider-python) — wrapped as MCP tools so any AI agent can call them without re-implementing reading rules, era arithmetic, postal data, or name-splitting heuristics.
Why this exists
Generic LLMs hallucinate on JP-specific data:
- "What year is 令和8年?" — often wrong
- "Convert 山田太郎 to romaji" — gets the surname wrong half the time
- "What's the address for postal code 150-0001?" — fabricates plausible-looking nonsense
- "Is May 3rd a Japanese holiday?" — guesses
This MCP gives them a deterministic answer.
Tools
| Tool | What it does |
|------|--------------|
| era_to_western | 令和8年 / R8 / Reiwa 8 / 令和元年 → Gregorian year + era metadata |
| western_to_era | 2026 → era kanji (令和), English (Reiwa), year-of-era (8), formatted strings |
| kanji_to_romaji | Mixed Japanese text → Hepburn romaji + hiragana reading |
| lookup_postal_code | 7-digit JP postal code → prefecture / city / area, with kana readings |
| is_holiday | Date string → is it a national holiday? + Japanese name + weekday |
| list_holidays | Year → all national holidays for that year |
| convert_kana | hiragana ↔ katakana ↔ half-width katakana, any direction |
| normalize_width | Full-width ↔ half-width for ASCII, digits, kana (with per-category control) |
| split_japanese_name | Japanese full name → surname + given name (statistical model with confidence) |
All tools return structured JSON. See tool docstrings in src/japan_utils_mcp/server.py for full schemas and examples.
Installation
Run with uvx (no install — recommended)
That's it. uvx (from uv) handles install + run in one shot, isolated from your global Python.
From source
Configuration
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Claude Code
Cursor / Cline / Continue
Same JSON snippet as Claude Desktop, in their respective MCP config files.
Examples
Once connected, ask your agent things like:
> **What year is 令和8年?**
> → era_to_western("令和8年") → 2026
> **What's the address for postal code 150-0001?**
> → lookup_postal_code("150-0001") → 東京都 渋谷区 神宮前