Japan Utils Mcp

Name: Japan Utils Mcp
Author: vivek081166

@vivek081166

About Japan Utils Mcp

MCP server exposing Japan-specific utilities (era conversion, romaji, holidays, postal codes, kana, name split) to AI agents.

#japan #japanese #romaji #postal-code #holidays #mcp #python #utilities #locale #nihongo

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "japan-utils": {
      "command": "uvx",
      "args": [
        "japan-utils-mcp"
      ]
    }
  }
}

Tools

`令和8年` / `R8` / `Reiwa 8` / `令和元年` → Gregorian year + era metadata

`2026` → era kanji (`令和`), English (`Reiwa`), year-of-era (`8`), formatted strings

Mixed Japanese text → Hepburn romaji + hiragana reading

7-digit JP postal code → prefecture / city / area, with kana readings

Date string → is it a national holiday? + Japanese name + weekday

Year → all national holidays for that year

hiragana ↔ katakana ↔ half-width katakana, any direction

Full-width ↔ half-width for ASCII, digits, kana (with per-category control)

Japanese full name → surname + given name (statistical model with confidence)

Overview

What is Japan Utils Mcp?

Japan Utils Mcp is an MCP (Model Context Protocol) server that exposes Japan-specific utilities to AI agents like Claude, Cursor, Cline, and Continue. It provides deterministic tools for tasks such as Japanese era-to-western year conversion, kanji-to-romaji transliteration, postal code lookup, national holiday queries, kana conversion, width normalization, and Japanese name splitting. It is built on well-maintained Japanese libraries (jpholiday, posuto, pykakasi, jaconv, namedivider-python) and wrapped as MCP tools for reliable, non-hallucinated answers.

How to use Japan Utils Mcp?

Install and run via uvx japan-utils-mcp (recommended, no install needed). Alternatively, clone the source repository, sync dependencies with uv sync, and run uv run japan-utils-mcp. Configure the server in your MCP client (e.g., Claude Desktop, Claude Code, Cursor) by adding a JSON entry with the uvx command and japan-utils-mcp argument to the client’s MCP configuration file.

Key features of Japan Utils Mcp

Era to western year conversion (Meiji through Reiwa)
Kanji to Hepburn romaji conversion
Japanese postal code lookup with address and kana readings
National holiday calendar (annual listing and single-date check)
Hiragana ↔ katakana ↔ half-width katakana conversion
Full-width to half-width normalization for ASCII, digits, and kana
Statistical Japanese name splitting into surname and given name
All tools return structured JSON for deterministic answers

Use cases of Japan Utils Mcp

Convert a Japanese era year (e.g., 令和8年) to its Gregorian equivalent (2026)
Look up the address for a 7-digit postal code (e.g., 150-0001 → 東京都渋谷区神宮前)
Transcribe a personal name like 山田太郎 into Hepburn romaji (yamada tarou)
Verify whether a specific date is a Japanese national holiday (e.g., 2026-05-03 → 憲法記念日)
Normalize mixed-width text (e.g., full-width ＡＢＣ to half-width ABC)

FAQ from Japan Utils Mcp

How does Japan Utils Mcp differ from asking a generic LLM?

Generic LLMs often hallucinate on Japan-specific data such as era arithmetic, romaji readings, postal addresses, and holidays. Japan Utils Mcp provides deterministic answers backed by well-maintained Japanese libraries, eliminating guesswork.

What are the runtime and dependency requirements?

The server requires Python and is designed to run via uvx from the uv tool. Dependencies (including jpholiday, posuto, pykakasi, etc.) are automatically resolved. Data is shipped locally; no external API calls or cloud services are needed.

Where does the postal code data come from and how fresh is it?

Postal code data is provided by the posuto library, which is refreshed against Japan Post's monthly KEN_ALL dataset. For ultra-fresh data, users should periodically update posuto.