Japan Utils Mcp

japan-utils-mcp

为 AI Agent（Claude、Cursor、Cline、Continue 等）提供日本专用工具的 MCP 服务。为 Agent 配备每项日本相关任务都需要、但通用大模型无法可靠处理的一组小型日本专用函数：

• 🗓️ 年号 ↔ 公历年份 — 令和8年 ↔ 2026
• 🔤 汉字 → 赫本式罗马字 — 山田太郎 → yamada tarou
• 📮 邮政编码查询 — 150-0001 → 東京都 渋谷区 神宮前
• 🎌 国家节假日日历 — 2026-05-03 是节假日吗？2026 年全年的节假日有哪些？
• 🅰️ 假名转换 — 平假名 ↔ 片假名 ↔ 半角片假名
• 📏 宽度标准化 — ASCII 字符、数字和假名的全角 ↔ 半角转换
• 👤 姓名拆分 — 山田太郎 → 姓氏 山田 + 名字 太郎（统计模型）

基于维护良好的日语库（jpholiday、posuto、pykakasi、jaconv、namedivider-python）构建，并封装为 MCP 工具，让任何 AI Agent 都能调用，而无需重新实现读音规则、年号换算、邮政数据或姓名拆分启发式算法。

为什么要做这个

通用大模型在日本专用数据上容易产生幻觉：

• “令和 8 年是公历哪一年？”——经常答错
• “把山田太郎转换为罗马字”——有一半概率会把姓氏读错
• “邮政编码 150-0001 对应什么地址？”——会编造看起来似乎合理的错误信息
• “5 月 3 日是日本的节假日吗？”——只能猜

这个 MCP 服务能提供确定的答案。

工具

工具	功能
era_to_western	令和8年 / R8 / Reiwa 8 / 令和元年 → 公历年份和年号元数据
western_to_era	2026 → 年号汉字（令和）、英文（Reiwa）、年号年份（8）和格式化字符串
kanji_to_romaji	混合日语文本 → 赫本式罗马字和对应的平假名读音
lookup_postal_code	7 位日本邮政编码 → 都道府县 / 市区町村 / 地区，以及假名读音
is_holiday	日期字符串 → 是否为国家节假日？+ 日文名称 + 星期几
list_holidays	年份 → 该年的所有国家节假日
convert_kana	平假名 ↔ 片假名 ↔ 半角片假名，可任意方向转换
normalize_width	ASCII 字符、数字和假名的全角 ↔ 半角转换（可按类别控制）
split_japanese_name	日文全名 → 姓氏 + 名字（带置信度的统计模型）

所有工具都返回结构化 JSON。完整的 schema 和示例请参见 src/japan_utils_mcp/server.py 中的工具文档字符串。

安装

使用 uvx 运行（无需安装——推荐）

uvx japan-utils-mcp

就这么简单。uvx（来自 uv）会一次性处理安装和运行，且与全局 Python 环境隔离。

从源代码安装

git clone https://github.com/vivek081166/japan-utils-mcp.git
cd japan-utils-mcp
uv sync
uv run japan-utils-mcp

配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

Claude Code

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

Cursor / Cline / Continue

在各自的 MCP 配置文件中添加与 Claude Desktop 相同的 JSON 片段。

示例

连接后，可以向 Agent 提出这样的问题：

令和 8 年是公历哪一年？ → era_to_western("令和8年") → 2026

邮政编码 150-0001 对应什么地址？ → lookup_postal_code("150-0001") → 東京都 渋谷区 神宮前

把山田太郎转换为罗马字。 → kanji_to_romaji("山田太郎") → yamada tarou

2026 年 5 月 3 日是日本的节假日吗？ → is_holiday("2026-05-03") → 憲法記念日（宪法纪念日）

列出 2026 年所有日本节假日。 → list_holidays(2026) → 18 个节假日及其名称和日期

把ヤマダタロウ转换为平假名。 → convert_kana("ヤマダタロウ", "hiragana") → やまだたろう

把ＡＢＣ１２３转换为半角。 → normalize_width("ＡＢＣ１２３", "to_half") → ABC123

把長谷川健太拆分为姓氏和名字。 → split_japanese_name("長谷川健太") → 長谷川 / 健太

注意事项

• 人名的罗马字转写采用最常见的读法——读法特殊的专有名词会出错。这是任何缺乏消歧上下文的汉字转罗马字转换所固有的局限。
• 邮政编码数据集通过 posuto 库提供，并根据日本邮政每月发布的 KEN_ALL 更新。如果需要极新的数据，请定期更新 posuto。
• 节假日仅涵盖全国性节假日（国民の祝日），不包括公司特定或地区性纪念日。
• 年号转换支持从明治（明治）到令和（令和）。不支持更早的年号。

开发

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

许可证

MIT