{
  "markdown": "# japan-utils-mcp\n\n<!-- mcp-name: io.github.vivek081166/japan-utils-mcp -->\n\n[![PyPI](https://img.shields.io/pypi/v/japan-utils-mcp.svg)](https://pypi.org/project/japan-utils-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nMCP 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:\n\n- 🗓️ **Era ↔ Western year** — `令和8年` ↔ `2026`\n- 🔤 **Kanji → Hepburn romaji** — `山田太郎` → `yamada tarou`\n- 📮 **Postal code lookup** — `150-0001` → `東京都 渋谷区 神宮前`\n- 🎌 **National holiday calendar** — is `2026-05-03` a holiday? what about all of 2026?\n- 🅰️ **Kana conversion** — hiragana ↔ katakana ↔ half-width katakana\n- 📏 **Width normalization** — full-width (全角) ↔ half-width (半角) for ASCII, digits, kana\n- 👤 **Name splitting** — `山田太郎` → surname `山田` + given `太郎` (statistical model)\n\nBuilt 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.\n\n## Why this exists\n\nGeneric LLMs hallucinate on JP-specific data:\n\n- \"What year is 令和8年?\" — often wrong\n- \"Convert 山田太郎 to romaji\" — gets the surname wrong half the time\n- \"What's the address for postal code 150-0001?\" — fabricates plausible-looking nonsense\n- \"Is May 3rd a Japanese holiday?\" — guesses\n\nThis MCP gives them a deterministic answer.\n\n## Tools\n\n| Tool | What it does |\n|------|--------------|\n| `era_to_western` | `令和8年` / `R8` / `Reiwa 8` / `令和元年` → Gregorian year + era metadata |\n| `western_to_era` | `2026` → era kanji (`令和`), English (`Reiwa`), year-of-era (`8`), formatted strings |\n| `kanji_to_romaji` | Mixed Japanese text → Hepburn romaji + hiragana reading |\n| `lookup_postal_code` | 7-digit JP postal code → prefecture / city / area, with kana readings |\n| `is_holiday` | Date string → is it a national holiday? + Japanese name + weekday |\n| `list_holidays` | Year → all national holidays for that year |\n| `convert_kana` | hiragana ↔ katakana ↔ half-width katakana, any direction |\n| `normalize_width` | Full-width ↔ half-width for ASCII, digits, kana (with per-category control) |\n| `split_japanese_name` | Japanese full name → surname + given name (statistical model with confidence) |\n\nAll tools return structured JSON. See tool docstrings in `src/japan_utils_mcp/server.py` for full schemas and examples.\n\n## Installation\n\n### Run with `uvx` (no install — recommended)\n\n```bash\nuvx japan-utils-mcp\n```\n\nThat's it. `uvx` (from [`uv`](https://docs.astral.sh/uv/)) handles install + run in one shot, isolated from your global Python.\n\n### From source\n\n```bash\ngit clone https://github.com/vivek081166/japan-utils-mcp.git\ncd japan-utils-mcp\nuv sync\nuv run japan-utils-mcp\n```\n\n## Configuration\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"japan-utils\": {\n      \"command\": \"uvx\",\n      \"args\": [\"japan-utils-mcp\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add japan-utils -- uvx japan-utils-mcp\n```\n\n### Cursor / Cline / Continue\n\nSame JSON snippet as Claude Desktop, in their respective MCP config files.\n\n## Examples\n\nOnce connected, ask your agent things like:\n\n> **What year is 令和8年?**\n> → `era_to_western(\"令和8年\")` → `2026`\n\n> **What's the address for postal code 150-0001?**\n> → `lookup_postal_code(\"150-0001\")` → `東京都 渋谷区 神宮前`\n\n> **Convert 山田太郎 to romaji.**\n> → `kanji_to_romaji(\"山田太郎\")` → `yamada tarou`\n\n> **Is May 3rd 2026 a Japanese holiday?**\n> → `is_holiday(\"2026-05-03\")` → `憲法記念日` (Constitution Memorial Day)\n\n> **List all Japanese holidays in 2026.**\n> → `list_holidays(2026)` → 18 holidays with names and dates\n\n> **Convert ヤマダタロウ to hiragana.**\n> → `convert_kana(\"ヤマダタロウ\", \"hiragana\")` → `やまだたろう`\n\n> **Normalize ＡＢＣ１２３ to half-width.**\n> → `normalize_width(\"ＡＢＣ１２３\", \"to_half\")` → `ABC123`\n\n> **Split 長谷川健太 into surname and given name.**\n> → `split_japanese_name(\"長谷川健太\")` → `長谷川` / `健太`\n\n## Caveats\n\n- **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.\n- **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.\n- **Holidays** covers national holidays (国民の祝日) only — not company-specific or regional observances.\n- **Era conversion** supports Meiji (明治) through Reiwa (令和). Earlier eras are not supported.\n\n## Development\n\n```bash\ngit clone https://github.com/vivek081166/japan-utils-mcp.git\ncd japan-utils-mcp\nuv sync\nuv run python -c \"from japan_utils_mcp.server import era_to_western; print(era_to_western('令和8年'))\"\n```\n\n## License\n\nMIT\n",
  "bytes": 5066,
  "sha": "70b69e6917c9b9e2458064a5fe547059dc2e9718f565dbac3f0e4c55614ca3b8",
  "repo_slug": "vivek081166/japan-utils-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vivek081166_japan_utils_mcp_81b3645f/readme"
}