jp-calendar-mcp
This server provides tools for Japanese business day, public holiday, TSE trading calendar, imperial era (wareki) conversion, and tax calculations.
Business Day & Calendar Tools
jp_check_date– Determines if a date is a weekend, public holiday, or business day (holidays 2020‑2031).jp_shift_days– Moves a date forward/backward by business or calendar days, skipping weekends and public holidays.jp_count_days– Counts calendar and business days between two dates.
TSE Trading Calendar
tse_is_trading_day– Checks if Tokyo Stock Exchange is open, providing closure reasons (e.g., year‑end break Dec 31–Jan 3).tse_shift_trading_days– Shifts a date by TSE trading days (e.g., T+2 settlement).tse_count_trading_days– Counts trading sessions between two dates.tse_year_summary– Returns first (大発会) and last (大納会) sessions and total sessions for a year.
Wareki Conversion
jp_to_wareki– Converts Gregorian (YYYY‑MM‑DD) to Japanese era (e.g., 令和元年5月1日).jp_from_wareki– Converts Japanese era (e.g., 昭和50年6月1日) to Gregorian, with warnings for out‑of‑era dates.
Tax Calculations
jp_ideco_tax_saving– Estimates income/residence tax savings from iDeCo contributions.jp_furusato_limit– Computes maximum furusato‑nozei donation limit with ¥2,000 out‑of‑pocket cost.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jp-calendar-mcp 2026年1月9日から営業日で1日後は?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
jp-calendar-mcp
MCP server for Japanese business days, public holidays, the Tokyo Stock Exchange trading calendar, 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 assume the stock exchange follows public holidays, 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
Tool | What it answers |
| Is this date a business day? Weekend? Public holiday? |
| "10 business days after 2026-01-09" (skips weekends + holidays) |
| Calendar days and business days between two dates |
| Is the Tokyo Stock Exchange open? With the closure reason |
| "T+2 settlement from 2025-12-30" → 2026-01-06, across the new-year break |
| Sessions between two dates (for annualising returns) |
| Sessions in a year plus its first/last session (大発会 / 大納会) |
| 2019-05-01 → 令和元年5月1日 (era boundaries handled to the day) |
| 昭和50年6月1日 → 1975-06-01, and flags out-of-era input |
| Annual income + residence tax reduction from iDeCo contributions |
| Donation limit that keeps the out-of-pocket cost at ¥2,000 |
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
The exchange calendar is not the holiday calendar
This trips up almost every implementation. TSE closures are a superset of public holidays: the exchange also closes 31 December through 3 January.
2026-01-02 public holiday? NO TSE open? NO (new_year_break)
2026-12-31 a normal work day TSE open? NO (year_end_break)
2026-12-30 a normal work day TSE open? YES (dainokai, last session)Because of that break, the first and last session move every year, and a +1 business day calculation gives the wrong answer for settlement:
Year | First session (大発会) | Last session (大納会) |
2024 | 2024-01-04 | 2024-12-30 |
2025 | 2025-01-06 | 2025-12-30 |
2026 | 2026-01-05 | 2026-12-30 |
All of the above are covered by the test suite as known-answer checks against actual sessions.
Install
git clone https://github.com/takeo628-hub/jp-calendar-mcp.git
cd jp-calendar-mcp
node test.js # 42 known-answer tests, no install step neededClaude 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 }
> 2025年最後の取引日から2営業日後(T+2受渡)
tse_shift_trading_days(date="2025-12-30", days=2)
→ { "date": "2026-01-06", "weekday": "火" }
(12/31-1/3 is the exchange break, so this is not "2 business days")
> 課税所得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 defaultAccuracy and limits
Holiday and exchange data cover 2020–2031. Outside that window a
noteis returned rather than a guess.The exchange calendar models scheduled closures only. Unscheduled halts (system failures, disasters) are historical events, not rules, and are not included.
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-30is 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
Available Tools
7 toolsjp_check_dateA
Check whether a Japanese calendar date is a business day. Returns weekday, weekend/public-holiday flags and a business-day flag. Public holidays are bundled for 2020-2031.
Inputs: date (required).
jp_count_daysA
Count calendar days and business days between two dates (Japanese holidays excluded from business days). Order of the two dates does not matter.
Inputs: end (required), start (required).
jp_from_warekiA
Convert a Japanese era date to the Gregorian calendar. Warns when the given month/day falls outside that era.
Inputs: day (required), era (required), month (required), era_year (required).
jp_furusato_limitA
Calculate the furusato-nozei (hometown tax donation) limit where the out-of-pocket cost stays at 2,000 yen, using the residence-tax income levy from the annual tax notice.
Inputs: taxable_income (required), residence_tax_income_levy (required).
jp_ideco_tax_savingA
Calculate the annual income-tax and residence-tax reduction from iDeCo contributions in Japan (contributions are fully deductible). Deduction effect only.
Inputs: taxable_income (required), monthly_contribution (required).
jp_shift_daysA
Move a date forward or backward by N days, either in business days (skipping weekends and Japanese public holidays) or calendar days. Negative values move backward.
Inputs: date (required), days (required), mode.
jp_to_warekiA
Convert a Gregorian date to the Japanese imperial era format (令和/平成/昭和/大正/明治). Era boundaries are handled to the day.
Inputs: date (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct operation: checking a date's business status, shifting by days, counting days between dates, and converting between Gregorian and Japanese eras. The two tax tools are also clearly separate from each other and from the calendar tools.
The common 'jp_' prefix helps, but the naming pattern is mixed: verb_noun (check_date, shift_days, count_days), directional (to_wareki, from_wareki), and noun phrases (ideco_tax_saving, furusato_limit). This inconsistency is noticeable but does not severely hinder readability.
Seven tools is a well-scoped count for a Japan-specific utility server. Each tool earns its place, and the set is neither bloated nor too thin.
The calendar tools cover the core business-day and era-conversion workflows thoroughly. The two tax tools are useful but feel like an add-on to a calendar-focused server, leaving some potential gaps in tax coverage.
Maintenance
Related MCP Connectors
Japanese business days, holiday checks and invoice due dates for your AI agent.
Japanese holiday and business-day calculations using official Japan Cabinet Office data.
Japanese national holidays, business days and wareki (era) dates, exact not guessed. No API key.
61MCP server for Japan geodata: cadastral lot numbers (chiban) and reverse geocoding, for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceA MCP server that provides timezone-aware date and time operations. This server addresses the common issue where AI assistants provide incorrect date information due to timezone confusion.45MIT
- AlicenseNot gradedqualityDmaintenanceJapanese calendar API for AI agents. Provides Rokuyo, Rekichu, Eto, 24 Solar Terms, and fortune judgments. MCP + REST API.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to perform Japanese business calendar calculations including holiday detection, business day arithmetic, payment date settlement, and deadline management using local data.6MIT
- AlicenseAqualityDmaintenanceMCP server providing AI agents with access to Japanese data APIs (address, furigana, transit, diet, holiday, weather, houjin) via a pay-per-use x402 payment protocol.2854 npm2Apache 2.0