Japan Utils

io.github.vivek081166Published by GitHub account vivek081166v0.1.2Updated Oct 27, 2026

Japan utilities for AI agents: era, romaji, postal codes, holidays, kana, name splitting.

VerifiedSTDIODesktop onlyLocation & LifestyleDeveloper Tools

Overview

AI-generated overview

Local MCP server giving assistants deterministic Japanese utilities: era conversion, romaji, postal codes, holidays, kana and name splitting.

What you can do
  • Convert between Japanese era names and Western years, in both directions
  • Transliterate mixed Japanese text to Hepburn romaji with hiragana readings
  • Look up Japanese postal codes for prefecture, city and area, and check or list national holidays by date or year
  • Convert between hiragana, katakana and half-width katakana, and normalize full-width and half-width characters
  • Split a Japanese full name into surname and given name using a statistical model
When to use it
Useful when an assistant regularly handles Japan-related tasks — addresses, dates, names, or text normalization — and you want exact answers instead of guesses. It suits agents working with Japanese forms, mailings, calendars or data cleanup.
Requirements
Runs as a local process over stdio, launched with uvx (from uv) or from source with uv; no accounts, API keys or environment variables are declared. Postal data ships with the posuto library.
Before you install
Read-only lookups; no credentials or writes are involved. Results are heuristic in places: romaji of personal names uses the most common reading, name splitting is statistical, holidays cover national holidays only, and era conversion stops at Meiji. Postal data is only as fresh as the bundled posuto dataset.

Installation

In SourceWeft

  1. Open Japan Utils in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

japan-utils-mcp

[PyPI] [License: MIT]

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

ToolWhat it does
era_to_western令和8年 / R8 / Reiwa 8 / 令和元年 → Gregorian year + era metadata
western_to_era2026 → era kanji (令和), English (Reiwa), year-of-era (8), formatted strings
kanji_to_romajiMixed Japanese text → Hepburn romaji + hiragana reading
lookup_postal_code7-digit JP postal code → prefecture / city / area, with kana readings
is_holidayDate string → is it a national holiday? + Japanese name + weekday
list_holidaysYear → all national holidays for that year
convert_kanahiragana ↔ katakana ↔ half-width katakana, any direction
normalize_widthFull-width ↔ half-width for ASCII, digits, kana (with per-category control)
split_japanese_nameJapanese 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)

bash
uvx japan-utils-mcp

That's it. uvx (from uv) handles install + run in one shot, isolated from your global Python.

From source

bash
git clone https://github.com/vivek081166/japan-utils-mcp.gitcd japan-utils-mcpuv syncuv run japan-utils-mcp

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code

bash
claude mcp add japan-utils -- uvx japan-utils-mcp

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") → 東京都 渋谷区 神宮前

Convert 山田太郎 to romaji. → kanji_to_romaji("山田太郎") → yamada tarou

Is May 3rd 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("長谷川健太") → 長谷川 / 健太

Caveats

  • Romaji of personal names uses the most common reading — proper nouns with unusual readings will be wrong. This is a fundamental limitation of any kanji-to-romaji conversion without disambiguation context.
  • Postal code dataset ships via the posuto library, refreshed against Japan Post's monthly KEN_ALL. If you need ultra-fresh data, refresh posuto periodically.
  • Holidays covers national holidays (国民の祝日) only — not company-specific or regional observances.
  • Era conversion supports Meiji (明治) through Reiwa (令和). Earlier eras are not supported.

Development

bash
git clone https://github.com/vivek081166/japan-utils-mcp.gitcd japan-utils-mcpuv syncuv run python -c "from japan_utils_mcp.server import era_to_western; print(era_to_western('令和8年'))"

License

MIT

Source: README.md at commit 56d203a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts