japan-utils-mcp

MCP 服务器，为 AI 代理（Claude、Cursor、Cline、Continue 等）提供日本专用工具。为你的代理提供一套处理日本相关任务时必不可少、但通用大模型往往无法准确处理的小型工具集：

• 🗓️ 元号 ↔ 西历 — 令和8年 ↔ 2026

• 🔤 汉字 → 黑本式罗马字 — 山田太郎 → yamada tarou

• 📮 邮政编码查询 — 150-0001 → 東京都 渋谷区 神宮前

• 🎌 国家法定节假日日历 — 2026-05-03 是节假日吗？2026 年全年有哪些节假日？

• 🅰️ 假名转换 — 平假名 ↔ 片假名 ↔ 半角片假名

• 📏 宽度标准化 — ASCII、数字、假名的全角 ↔ 半角转换

• 👤 姓名拆分 — 山田太郎 → 姓 山田 + 名 太郎（基于统计模型）

基于维护良好的日本相关库（jpholiday、posuto、pykakasi、jaconv、namedivider-python）构建，并封装为 MCP 工具，使任何 AI 代理无需重新实现阅读规则、元号计算、邮政数据或姓名拆分启发式算法即可调用。

为什么存在这个项目

通用大模型在处理日本特定数据时常会出现幻觉：

• “令和8年是哪一年？” — 经常出错

• “将山田太郎转换为罗马字” — 姓氏转换有一半概率出错

• “邮政编码 150-0001 的地址是什么？” — 编造看似合理的错误信息

• “5月3日是日本的节假日吗？” — 靠猜

此 MCP 为它们提供了确定性的答案。

工具

所有工具均返回结构化的 JSON。有关完整架构和示例，请参阅 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

与 Claude Desktop 使用相同的 JSON 片段，放入它们各自的 MCP 配置文件中。

示例

连接后，你可以向代理询问如下问题：

令和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。

• 节假日 仅涵盖国家法定节假日（国民の祝日）—— 不包括公司特定或地区性的纪念日。

• 元号转换 支持从明治（Meiji）到令和（Reiwa）。不支持更早的元号。

开发

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