japan-utils-mcp

AI 에이전트(Claude, Cursor, Cline, Continue 등)에 일본 관련 유틸리티를 제공하는 MCP 서버입니다. 일본 관련 작업 시 일반적인 LLM이 정확하게 처리하지 못하는 일본 특화 기능을 에이전트에게 제공합니다:

• 🗓️ 연호 ↔ 서기 — 令和8年 ↔ 2026

• 🔤 한자 → 헵번식 로마자 — 山田太郎 → yamada tarou

• 📮 우편번호 조회 — 150-0001 → 東京都 渋谷区 神宮前

• 🎌 공휴일 달력 — 2026-05-03은 공휴일인가요? 2026년 전체 공휴일은 언제인가요?

• 🅰️ 가나 변환 — 히라가나 ↔ 가타카나 ↔ 반각 가타카나

• 📏 폭 정규화 — ASCII, 숫자, 가나에 대한 전각(全角) ↔ 반각(半角) 변환

• 👤 이름 분리 — 山田太郎 → 성 山田 + 이름 太郎 (통계 모델 기반)

검증된 일본어 라이브러리(jpholiday, posuto, pykakasi, jaconv, namedivider-python)를 기반으로 구축되었으며, MCP 도구로 래핑되어 있어 AI 에이전트가 읽기 규칙, 연호 계산, 우편 데이터, 이름 분리 휴리스틱을 직접 구현할 필요 없이 호출할 수 있습니다.

존재 이유

일반적인 LLM은 일본 관련 데이터에서 환각 현상을 보입니다:

• "令和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를 주기적으로 업데이트하세요.

• 공휴일은 국가 공휴일(国民の祝日)만 포함하며, 회사별 또는 지역별 휴일은 포함하지 않습니다.

• 연호 변환은 메이지(明治)부터 레이와(令和)까지 지원합니다. 이전 연호는 지원하지 않습니다.

개발

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