Purpose
japan-utils-mcp is an MCP (Model Context Protocol) server that exposes common Japan-related utility capabilities to AI agents, such as Claude, Cursor, Cline, Continue, etc. It provides deterministic processing results for the problem that general-purpose large models are prone to errors or hallucinations on Japan-specific data.
Main Capabilities
- Japanese era <-> Gregorian year conversion: for example, Reiwa 8 <-> 2026. Supports era names ranging from Meiji (Meiji) to Reiwa (Reiwa).
- Kanji -> Hepburn romanization: for example, 山田太郎 -> yamada tarou.
- Postal code lookup: for example, 150-0001 -> 東京都 渋谷区 神宮前.
- Japanese statutory holiday calendar: can determine whether a date is a holiday, and can also list all holidays for a given year.
- Kana conversion: hiragana <-> katakana <-> half-width katakana.
- Width normalization: full-width (全角) <-> half-width (半角) conversion for ASCII, digits, and kana.
- Personal name splitting: for example, 山田太郎 -> surname 山田 + given name 太郎 (statistical model).
This server is built on well-maintained Japanese language libraries: jpholiday, posuto, pykakasi, jaconv, namedivider-python. All tools return structured JSON; the complete schema and examples can be found in the tool docstrings in src/japan_utils_mcp/server.py.
Usage
Running with uvx is recommended; no installation is required, it is isolated from the global Python environment, and installation and execution can be completed with a single command.
Add the corresponding JSON to the Claude Desktop configuration file (the macOS path is ~/Library/Application Support/Claude/claude_desktop_config.json, and the Windows path is %APPDATA%\Claude\claude_desktop_config.json). Cursor / Cline / Continue use the same JSON snippet, placed in their respective MCP configuration files.
After connecting, you can make requests to the agent such as:
- What year is Reiwa 8? -> era_to_western("令和8年") → 2026
- What is the address for postal code 150-0001? → lookup_postal_code("150-0001") → 東京都 渋谷区 神宮前
- Convert 山田太郎 to romaji. → kanji_to_romaji("山田太郎") → yamada tarou
- Is May 3, 2026 a Japanese holiday? → is_holiday("2026-05-03") → 憲法記念日 (Constitution Memorial Day)
- List all Japanese holidays in 2026. → list_holidays(2026) → 18 holidays with names and dates
- Convert ヤマダタロウ to hiragana. → convert_kana("ヤマダタロウ", "hiragana") → やまだたろう
- Normalize ＡＢＣ１２３ to half-width. → normalize_width("ＡＢＣ１２３", "to_half") → ABC123
- Split 長谷川健太 into surname and given name. → split_japanese_name("長谷川健太") → 長谷川 / 健太
Use Cases
Suitable for any agent task involving Japanese data: when you need to accurately calculate era years, when you need to transliterate Japanese personal names or addresses into romaji, when you need to look up the address corresponding to a Japanese postal code, when you need to determine Japanese holidays, when you need to unify full-width and half-width characters, or when you need to split Japanese personal names. These are fine-grained capabilities that Japanese-related tasks often require but general-purpose large models often cannot handle reliably.
Limitations
- Personal name romaji conversion uses the most common reading, and will make mistakes for proper nouns with unusual readings. This is a fundamental limitation of any kanji-to-romaji scheme without disambiguation context.
- The postal code dataset is provided through the posuto library and is kept refreshed in line with Japan Post's monthly KEN_ALL data. If extremely recent data is needed, please refresh posuto periodically.
- Holidays cover only national statutory holidays (国民の祝日) and do not include company-specific or regional holidays.
- Era conversion supports Meiji (明治) through Reiwa (令和). Earlier eras are not supported.
(Note: The official materials do not provide specific installation command text, version numbers, or pricing information, so the related content is not provided for now.)
