jp-calendar-mcp

MCP server for Japanese business days, public holidays, imperial-era (wareki) dates and tax arithmetic. Zero dependencies, runs on plain Node 18+.

AI agents get Japanese dates wrong in specific, repeatable ways: they miss 成人の日 landing on a Monday, they put the 平成→令和 boundary on the wrong day, and they invent furusato-nozei limits. These are lookup and arithmetic problems, not reasoning problems, so this server answers them exactly.

Tools

Public holidays are bundled for 2020–2031 (generated with the jpholiday library, including substitute holidays and the moving equinox dates). Dates outside that range return a note saying only weekends were excluded — the server never silently guesses.

Related MCP server: shirabe-calendar-api

Install

git clone https://github.com/takeo628-hub/jp-calendar-mcp.git
cd jp-calendar-mcp
node test.js     # 27 known-answer tests, no install step needed

Claude Code / Claude Desktop

{
  "mcpServers": {
    "jp-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/jp-calendar-mcp/src/index.js"]
    }
  }
}

Examples

> 2026年1月9日から営業日で1日後は？
jp_shift_days(date="2026-01-09", days=1)
→ { "date": "2026-01-13", "weekday": "火", "mode": "business" }
   (1/10-11 is a weekend and 1/12 is 成人の日)

> 平成31年4月30日を西暦で
jp_from_wareki(era="平成", era_year=31, month=4, day=30)
→ { "gregorian": "2019-04-30", "matches_era": true }

> 課税所得300万でiDeCo月2.3万の節税額
jp_ideco_tax_saving(monthly_contribution=23000, taxable_income=3000000)
→ { "annual_tax_saving": 55780, "income_tax_rate": 0.1 }

Also available as plain JavaScript

import { shiftDays, toWareki } from "jp-calendar-mcp";
shiftDays("2026-01-09", 1);   // business days by default

Accuracy and limits

• Holiday data covers 2020–2031. Outside that window only weekends are excluded and a note is returned.

• Tax tools implement the standard published formulas: iDeCo contributions are fully deductible (income tax including the 2.1% reconstruction surtax, plus 10% residence tax); the furusato limit uses the residence-tax income levy formula. Contribution caps and tax rules change, and individual circumstances vary — verify before acting. This is arithmetic, not tax advice.

• Invalid input raises an error rather than returning a plausible-looking wrong answer. 2026-02-30 is rejected; an unknown era is rejected; a wareki date outside its era is returned with a warning.

Why it exists

Built by an autonomous AI development loop that publishes everything it does, including its failures: https://takeo628-hub.github.io/autoquant-lab/

License

MIT