japan-utils-mcp
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 为它们提供了确定性的答案。
Related MCP server: Torify — Japanese Locale APIs for AI Agents
工具
工具 | 功能 |
|
|
|
|
| 混合日语文本 → 黑本式罗马字 + 平假名读音 |
| 7 位日本邮政编码 → 都道府县 / 市区町村 / 区域,包含假名读音 |
| 日期字符串 → 是否为国家法定节假日?+ 日本名称 + 星期 |
| 年份 → 该年度所有国家法定节假日 |
| 平假名 ↔ 片假名 ↔ 半角片假名,支持任意方向 |
| ASCII、数字、假名的全角 ↔ 半角转换(支持按类别控制) |
| 日本全名 → 姓 + 名(带置信度的统计模型) |
所有工具均返回结构化的 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-mcpCursor / 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")→やまだたろう
将 ABC123 标准化为半角。 →
normalize_width("ABC123", "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
Available Tools
9 toolsconvert_kanaA
Convert between hiragana, katakana, and half-width katakana.
Args: text: Input string. Mix of hiragana, katakana, kanji, ASCII is fine — non-target characters pass through unchanged. to: Target script. One of: - 'hiragana' : ひらがな (e.g. ヤマダ → やまだ) - 'katakana' : カタカナ (full-width) (e.g. やまだ → ヤマダ) - 'half_kana' : ハンカクカタカナ (half-width katakana) (e.g. ヤマダ → ヤマダ) - 'full_kana' : ヤマダ (half-width → full-width katakana)
Returns: dict with keys: - input: str - output: str - to: str
Examples: convert_kana("ヤマダタロウ", "hiragana") → "やまだたろう" convert_kana("やまだたろう", "katakana") → "ヤマダタロウ" convert_kana("ヤマダ", "half_kana") → "ヤマダ" convert_kana("ヤマダ", "full_kana") → "ヤマダ"
Inputs: text (required), to (required). Returns: object
era_to_westernA
Convert a Japanese era year to a Western (Gregorian) year.
Args: era_year: An era-year string. Accepts kanji form ('令和8年', '令和8', '令和元年'), single-letter alias ('R8', 'H30'), or English alias ('Reiwa 8', 'Heisei 30').
Returns: dict with keys: - western_year: int (Gregorian year) - era_kanji: str (e.g. '令和') - era_english: str (e.g. 'Reiwa') - year_of_era: int
Examples: era_to_western("令和8年") → {"western_year": 2026, ...} era_to_western("R8") → {"western_year": 2026, ...} era_to_western("Reiwa 8") → {"western_year": 2026, ...}
Inputs: era_year (required). Returns: object
is_holidayA
Check whether a date is a Japanese national holiday (祝日).
Args: date_str: Date in 'YYYY-MM-DD', 'YYYY/MM/DD', or 'YYYYMMDD' format.
Returns: dict with keys: - date: str (normalized 'YYYY-MM-DD') - is_holiday: bool - name_jp: str | None (holiday name in Japanese, if applicable) - weekday_jp: str (e.g. '月', '火', ...) - weekday_en: str (e.g. 'Monday')
Examples: is_holiday("2026-05-03") → {"is_holiday": True, "name_jp": "憲法記念日", ...} is_holiday("2026-05-04") → {"is_holiday": True, "name_jp": "みどりの日", ...} is_holiday("2026-05-08") → {"is_holiday": False, "name_jp": None, ...}
Notes: - Covers national holidays only (祝日 designated by the 国民の祝日に関する法律). Does not cover company-specific or regional observances. - 振替休日 (substitute holidays) are correctly identified.
Inputs: date_str (required). Returns: object
kanji_to_romajiA
Transliterate Japanese text (kanji + kana mix) to Hepburn romaji.
Args: text: Japanese text. May contain kanji, hiragana, katakana, ASCII. Non-Japanese characters pass through unchanged.
Returns: dict with keys: - romaji: str (space-separated Hepburn romaji) - hiragana: str (kanji converted to hiragana, kana preserved) - input: str (echo of the original input)
Examples: kanji_to_romaji("山田太郎") → {"romaji": "yamada tarou", "hiragana": "やまだたろう"} kanji_to_romaji("東京駅") → {"romaji": "toukyou eki", "hiragana": "とうきょうえき"}
Caveats: - Kanji with multiple readings (e.g. proper nouns) may be ambiguous. The transliteration uses the most common reading, which is sometimes wrong for personal names. Use as a starting point, not a guarantee.
Inputs: text (required). Returns: object
list_holidaysA
List all Japanese national holidays for a given year.
Args: year: Western year (e.g. 2026).
Returns: dict with keys: - year: int - count: int - holidays: list of {date: 'YYYY-MM-DD', name_jp: str, weekday_en: str}
Examples: list_holidays(2026) → {"year": 2026, "count": 16, "holidays": [...]}
Inputs: year (required). Returns: object
lookup_postal_codeA
Look up a Japanese postal code (郵便番号) and return address components.
Args: postal_code: 7-digit JP postal code. Accepts '150-0001', '1500001', '150 0001', or with full-width digits.
Returns: dict with keys: - postal_code: str (normalized 7-digit form) - prefecture: str (都道府県) - city: str (市区町村) - area: str (町域 — neighborhood/area) - prefecture_kana: str (katakana reading of prefecture) - city_kana: str - area_kana: str - found: bool (true if the code resolved)
Examples: lookup_postal_code("150-0001") → { "postal_code": "1500001", "prefecture": "東京都", "city": "渋谷区", "area": "神宮前", ... "found": True, }
Inputs: postal_code (required). Returns: object
normalize_widthA
Convert between half-width (半角) and full-width (全角) characters.
Args: text: Input string. mode: Conversion direction. One of: - 'to_full' : half-width → full-width for all categories (kana, ascii, digits) - 'to_half' : full-width → half-width for all categories - 'to_full_ascii_only' : convert only ASCII letters and digits to full-width, leave kana untouched - 'to_half_ascii_only' : convert only full-width ASCII to half-width - 'to_full_kana_only' : convert only half-width katakana to full-width - 'to_half_kana_only' : convert only full-width katakana to half-width
Returns: dict with keys: - input: str - output: str - mode: str
Examples: normalize_width("ABC123", "to_half") → "ABC123" normalize_width("ABC123", "to_full") → "ABC123" normalize_width("カタカナ", "to_full") → "カタカナ"
Inputs: text (required), mode. Returns: object
split_japanese_nameA
Split a Japanese full name into surname (姓) and given name (名).
Uses a kanji-feature-based statistical model (namedivider-python).
Args: full_name: Japanese full name written in kanji, with no separator (e.g. '山田太郎', '長谷川健太'). Names with existing separators (space, comma) are also accepted — the separator will be re-detected.
Returns: dict with keys: - input: str - family: str (姓 — surname) - given: str (名 — given name) - confidence: float (0.0–1.0; higher = more confident split) - algorithm: str (which underlying algorithm produced the split)
Examples: split_japanese_name("山田太郎") → {"family": "山田", "given": "太郎", ...} split_japanese_name("長谷川健太") → {"family": "長谷川", "given": "健太", ...} split_japanese_name("佐藤花子") → {"family": "佐藤", "given": "花子", ...}
Caveats: - Statistical model — not 100% accurate, especially for unusual names or non-traditional name compositions. - Confidence < 0.5 indicates an ambiguous split; treat with caution. - Single-kanji surnames + single-kanji given names (e.g. '林修') are fundamentally ambiguous without external context.
Inputs: full_name (required). Returns: object
western_to_eraA
Convert a Western (Gregorian) year to its Japanese era year.
Note: this returns the era in effect for the majority of the given Gregorian year. For year transitions (e.g. 1989 split between 昭和64 and 平成1), it returns the newer era.
Args: year: Western year (e.g. 2026). Must be 1868 or later.
Returns: dict with keys: - era_kanji: str - era_english: str - year_of_era: int (1 for the first year of an era; written as 元年 in formal Japanese) - era_year_kanji: str (e.g. '令和8年') - era_year_short: str (e.g. 'R8')
Examples: western_to_era(2026) → {"era_kanji": "令和", "era_english": "Reiwa", "year_of_era": 8, "era_year_kanji": "令和8年", "era_year_short": "R8"}
Inputs: year (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a unique operation – kana conversion, era conversion, holiday checking, romaji transliteration, postal code lookup, width normalization, name splitting, and era-to-Western conversion. There is no functional overlap or ambiguity.
All tool names follow a consistent snake_case pattern with verb + noun or noun + verb structure (e.g., convert_kana, is_holiday, list_holidays). No mixed case or inconsistent styles.
With 9 tools covering a broad set of Japanese language utilities (kana, kanji, eras, holidays, addresses, names), the number feels well-scoped. Enough to be useful without being overwhelming.
The set covers essential Japanese text operations: kana/width normalization, romaji, era conversion both ways, holiday queries (single and list), postal code lookup, and name splitting. Minor gaps like lunar calendar or date formatting exist but do not undermine core utility.
Maintenance
Related MCP Connectors
Japan data tools for AI agents: calendar (rokuyo), address, name splitting, corporate number lookup
39 Japanese locale APIs — wareki, NTA invoice, 法人番号, postal, romanization, kanji-kana (Workers AI).
Japanese business days, holiday checks and invoice due dates for your AI agent.
13 free utility tools for AI agents: web text, markdown, hashing, IDs, dates, units, JSON.
Related MCP Servers
- AlicenseAqualityCmaintenanceJapan Operations OS for AI agents — 14 knowledge domains covering regulations, protocols, calendar, travel, food culture, language, disaster safety, daily life, and persistent memory. 31 MCP tools via REST + Streamable HTTP.31MIT
- AlicenseNot gradedqualityDmaintenanceTorify gives AI agents the Japanese locale primitives that standard libraries lack — imperial era date conversion (wareki), qualified invoice number validation with NTA registry lookup, corporate number lookup (法人番号), postal code resolution, name romanization (Hepburn), and kanji-to-kana conversion via Yahoo! JLP. 31 endpoints total. No authentication required for MCP. Pay-per-call $0.02/call viaMIT
- AlicenseAqualityDmaintenancePortable agent tools with typed schemas (diff, cron, units, JSON→TS, outdoor helpers, prompts). Free to try—no account required.30MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to geocode Japanese addresses, retrieve GSI map tiles, query e-Stat statistics, and access MLIT school-district and real-estate-related geospatial data, with core tools requiring no API keys.MIT